Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[DOCS] Improve readability of module indexes in Furo theme #368

Open
barbaricyawps opened this issue Mar 9, 2023 · 0 comments
Open

[DOCS] Improve readability of module indexes in Furo theme #368

barbaricyawps opened this issue Mar 9, 2023 · 0 comments

Comments

@barbaricyawps
Copy link

barbaricyawps commented Mar 9, 2023

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant