You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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...
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.
The text was updated successfully, but these errors were encountered:
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.
This is readable:
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...
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.
The text was updated successfully, but these errors were encountered: