Comment on SaltStack Grains doco

http://docs.saltstack.com/topics/targeting/grains.html#writing-grains
>It is important to remember that grains are bits of information loaded when the salt minion starts, so this information is static. This means that the information in grains is unchanging, therefore the nature of the data is static.


Seriously - what? Suggestions for clearer, more helpful statements, if true:
- Grains are loaded when the minion starts, and cannot be changed at runtime.
- If grains are used for information that may change, unpredictable results may occur.


>Grains can also be statically assigned within the minion configuration file
Where is this file?


> This simple example is nice, but too much of the code is similar.
This “simple example” is way more readable than the jinja mess. And what exactly is the point? All you’ve done is move the specification of roles out of one file (top.sls) into another (minion config file). [When I say, “what’s the point”, I mean - make it clear to the user what the point is, if there is one.]


>WRITING GRAINS \ Grains are easy to write.
Wait, how can we “write” a grain? So far grains have been described as being “bits of information loaded when the salt minion starts”. You can’t “write” a bit of information. So you must be writing something different from a grain itself. I think a different word is needed here, or the double meaning clearly explained.

>Custom grain modules in _grains directory, synced to minions.
Where is this _grains directory (give default location), how is it “synced to minions”? Do you just mean it goes in the same place as .sls files? No need to mention syncing then…

>The core module in the grains package is where the main grains are loaded by the Salt minion and provides the principal example of how to write grains:
Wait, your example of how to write a custom grain is….the core module? That 1400 line file is very unhelpful. Is there not a single real example of a custom grain? You did say "Grains are easy to write.”