Comments on SaltStac documentation

Comments on salt doco

Disclaimer: it's hard finding the right time to comment on docs because either:
- you comment too early, before you really understand anything, and it's hard to describe what you're having trouble understanding
- you comment too late, and now you understand everything and the doc seems to make sense now.

Confusing having both docs.saltstack (with several versions and lots of developer doc mixed in) and salt.readthedocs.org

No clear understanding of the names of the different bits in a .sls file: state, component, function, id, module
[solution here is not another page, but just to highlight those terms where used, and be consistent]

Unclear to me what the rules of the yaml file are: can you repeat function names? Most of the examples are kind of trivial
and don't cover real cases. Example: embedded bash examples are all single line. Took a bit of searching on stackoverflow to
discover how to do multi-line bash (with | character).

Requisites (http://docs.saltstack.com/ref/states/requisites.html)
- no examples of depending on more than one thing
- no explanation of what the 'vim' in 'pkg: vim' refers to (is it the package name, or the id of the component that installed it)

pgkrepo: I was trying to find the equivalent of apt-add-repository and assumed salt.modules.apt.mod_repo was the right one. It didn't work,
but eventually pkgrepo.managed did the trick - but it's hard to find (I came across a forum post that guided me).

*Really* unclear to me where order matters and where it doesn't. Specifically:
- order of states in top file
- order of components (is that what they're called?) in state file
- order of functions within component

Confusing to me that in much of the doc, the examples are command line commands (eg from http://docs.saltstack.com/ref/modules/all/salt.modules.apt.html):

salt '*' pkg.del_repo "myrepo definition"
----
Also confusing: some functions specify their behaviour as if they were Python functions:
"
Returns a dict of dicts containing the state, and package names:

{'<host>':
    {'<state>': ['pkg1',
                 ...
                ]
    },
    ...
}"

(I really can't understand how to use this apt.get_selections function, or why I would want to...)

Suggestion: every function should have a meaningful .sls example.
----
http://docs.saltstack.com/topics/tutorials/walkthrough.html
IMHO the 'official walkthrough' should start with something more interesting than how to install the master and minion. For someone evaluating Salt, it's quite a slog through this tedium before you get anywhere like *why* you would want to do this. I'd suggest cutting it back to the bare essentials, removing the verbosity (eg, giving two different ways to start the minion - you don't need that yet).

Similarly, it's confusing explaining the targeting system before you have anything to run. And the stuff about verifying keys can surely come later.

The "note" under Salt States is unfortunately completely meaningless to a newbie. It's well-intentioned, but all a newbie can take from it is "Salt does stuff with states."

>The state system is built on sls formulas

Meaning? What's an SLS formula? Is a .sls file a 'state' or an 'sls formula'? You can read through the whole 'Salt States' section and still have no idea what a 'state' is. Is it just a Salt abstraction that is not exposed directly to the end user? If so, why does the user need to know about it now?

>Adding Some Depth¶
Here would be a good place to use some formatting and links to highlight terms like 'formula', 'statement' etc. It'd also be nice to label what the whole unit of content from 'nginx:' downwards is called (I think 'component'?)

> Obviously maintaining sls formulas right in the root of the file server will not scale out to reasonably sized deployments.
I didn't understand this sentence at all. Was there a previous version of this doc where the .sls file was stored in /?

(Wait, maybe I do. It's saying you shouldn't put all your .sls files in /srv/salt, but under subdirectories? If so, IMHO it's way too early to get into niceties. Surely that will only be a problem when you have a dozen or more formulas...)

>nginx:
>  pkg:
>    - installed
>  service:
>    - running
>    - require:
>      - pkg: nginx

As a newbie, I found this example pretty underwhelming. 7 lines, of which the last two appear to be repetitive and redundant. "Install nginx. Then, if nginx has been installed, start the service." Is this really necessary? Wouldn't ordering suffice?