salt-ext-modules-vmware icon indicating copy to clipboard operation
salt-ext-modules-vmware copied to clipboard

[DOCS] Improve readability of module indexes in Furo theme

Open barbaricyawps opened this issue 2 years ago • 0 comments

David Fidler reports on Slack:

For this topic: https://docs.saltproject.io/salt/extensions/salt-ext-modules-vmware/en/latest/vmc.html#modules-and-states-for-controlling-vmc-sddc

The new docs format is not readable.

left-nav-bar-wrap

This is readable:

core-module-index

For the new theme, the problem is a whitespace and wordwrap issue. The only issue with the core module display index is that there's no single-line summary, it's just a list. But it is easily searchable/browseable. For example, "ctrl-f ansible" finds me the ansible modules on the core Salt modules. But also highlights other substrings. It's clean, simple.

By contrast, the new doc format creates a hierarchy, which is not easily browseable... it's too "vmware." It's fine for the install guide, but not for module docs (IMHO). I think part of the problem is the verbosity of the module name string... I searched for "host" in there and got this...

search results

It's just not very readable or user friendly to go through that search results list and the fact that there is wordwrap on the LHS means it's longer than it should be. Don't get me wrong, the search engine is a nice touch - in that it searches the sub-pages/module docs. My concern is less about the SDDC modules right now and more that we'd try to transition the existing docs to that format. I think that would a step in the wrong direction.

barbaricyawps avatar Mar 09 '23 23:03 barbaricyawps