Salt: Improve the "flow" of Salt documentation

[whiteinge]

Many of the Salt docs are "dead-ends". Meaning you land on a page that explains something and there's rarely links to deeper explanations or related topics. When there are links they are typically embedded in the text and not friendly to skimming.

Here is an example. Say you land on the main States documentation http://docs.saltstack.com/ref/states/. How do you get from that main page to any of the sub-pages (and there are many)?

For example, that main page has a section on the top file but no link to this page:
http://docs.saltstack.com/ref/states/top.html

I have no idea how to get to this page without going through the Full Table of Contents:
http://docs.saltstack.com/ref/states/vars.html

I think a big part this problem was (my) decision to have a monolithic, stand-alone table of contents (contents.rst). Although that makes it easy to globally reorder the entire documentation it avoids smaller section-local table of contents. There's probably a good middle-ground; let's find it.

[whiteinge]

Issue #9810 is another great example of this.

[gravyboat]

Making note of https://github.com/saltstack/salt/issues/9974.

[cachedout]

+1 to this. I'm in for helping however I can.

[gravyboat]

Another note here. I think when we redesign some of the content we should ensure that pages have more 'headlines' which can easily be linked to. This helps populate the table of contents and is really useful when linking in the IRC to avoid suggestions such as 'follow this link, then look 4 paragraphs down.'.

[gravyboat]

Something else that's come up quite a bit is the confusion between the module docs, and the state docs. I think we should try to emphasize the difference and explain this more thoroughly.

[gravyboat]

http://docs.saltstack.com/topics/pillar/ and http://docs.saltstack.com/topics/tutorials/pillar.html should either be merged, or modified in some way to make them 'work' better together, since there is critical data throughout. We should also mention http://docs.saltstack.com/ref/modules/all/salt.modules.pillar.html This seems like a lot of pages that are associated with the same thing.

[JensRantil]

Something else that's come up quite a bit is the confusion between the module docs, and the state docs. I think we should try to emphasize the difference and explain this more thoroughly.

I'm a beginner with Salt. I totally agree with this.

[gravyboat]

A user brought up that they feel an example such as the django docs are still difficult to navigate, and something like: http://docs.python.org/2/index.html is better.

[whiteinge]

Refs #12446.

[jaloren]

Here's my suggestion for improving the flow.

https://github.com/saltstack/salt/issues/13358

[jacobhammons]

There have been many changes since this was opened to address the flow of the documentation, I think with the full TOC displaying in the right navigation and the TOC reorganization in 2016.3.0 this is mostly solved. I'm going to close this with the recommendation that new issues be opened if there are still issues with flow.