From the community survey results so far (BTW, please take it if you have not already) - ttps://www.surveymonkey.com/s/9PCHKDK - it becomes clear that many of you would like some documentation restructuring. We get about equal numbers of “the docs are great, this is so much better than X, and it’s easy to find things” and a lot about examples being needed and it being hard to find things.
Besides an index, where I think the doc needs more indexing, I think the most important thing is to reorganize into more sections/chapters (not less) and also work more examples and a tutorial into things.
However, I realize everybody also learns differently.
I have two general suggestions that you may have already sort of captured:
- Like you said, more sections, grouped by function. Right now the
"playbooks" and "advanced playbooks" pages are getting a bit unwieldy.
Creating a little more hierarchy might be useful.
- A full top-to-bottom documented walkthrough of one of our
ansible-examples would be fantastic. I use lamp_haproxy all the time
when I'm talking about Ansible, so it might be a good starting point.
It also uses probably 80% of the most critical Ansible features.
First up the docs are classes better than other projects. So we're really talking
about icing the cake here :-).
(A)
It *might* be worth doing a monkey-see-monkey-do tutorial, where the user can
see the playbook evolving as more & more functionality is added.
- evolving a simple deployed & vanilla box by ansible-ifying its config (ssh keys, std account etc)
- adding a couple of packages and to it
- showing how to parameterise this package to work on different flavours of linux (introduce vars & referring to config)
- transferring in a new set of ssh host keys (passwords, copy, fetch, handlers to trigger restart if required)
- re-using this config to spawn up a few identical configs on e.g. EC2
- applying set configurations to those configs (IIRC like in Lester Wade's Euca demo with web & db configs)
This is probably far enough to leave people with the fancy docs from here on.
(B)
I'd actually like a single-page HTML reference that duplicates all the current
content. This allows me to ctrl-f find very quickly the specific reference I
am looking for. In particular I often get lost between e.g. playbooks.html and
playbooks2.html when I'm looking for something.
I’d also like to see a single html page documentation for the given reasons (i.e. full text search). This should then be combined with a sticky header that includes a drop-down of the whole structure so that chapters/sections can be jumped to directly from anywhere in the document.
I think we can fix the playbooks, playbooks2 problem by having more specific sections like maybe something called “Variables”, “Conditionals and Loops” or “Variables” and so on.
This way you can still eyeball things without infinite scroll.
I suspect the concept of an advanced section will completely go away, and some chapters might end up being pretty short.
I personally like the https://readthedocs.org/ approach for webbased viewing. Other than that here are some things I’d like to share :
a lot of info is available here in this mailing list. I once had the idea of skimming through it and consolidate the usefull things somewhere. But at this rate I’m not sure I’ll get to it
an offline well structured document would be nice. pdf, epub…I personally haven’t read the docs on the Ansibleworks website from start to finish. Always parts and I’ve a feeling I’m missing usefull info.
The documentation could really use a section on variable interpolation. Depending on how a variable is set and where it is referenced, results vary greatly, and that’s really pretty much glossed over in the current documentation.
Cases I’ve run into:
spaces in {{ }} don’t matter, unless you’re passing a value to a task in “var=value” format. If you’re doing that, you cannot have any spaces inside the {{}}, or the tokenizer will break.
variables set in an inventory file cannot be interpreted as booleans; variables set from “vars:” clause are evaluated as booleans without difficulty.
access to the hostvars structure can be a bit tricky. Some examples showing variables to access dictionary keys would be good.
Those are the primary stumbling blocks I’ve run into which I couldn’t solve with the existing documentation.
In the past year Ansible has become somewhat more complex -- or call
it more mature :). Right now it could use specific documentation that
would help a new guy inherit a project and hit the ground running. Or
help someone become reacquainted with their own code after some time
away from it. With this in mind, two suggestions:
- A reference for deprecated syntax. Deprecations appear in the
changelog, but obscured by the new features, and not in a
newb-friendly two column before/after format with examples and
gotchas.
- A section with an exhaustive reference of lookup plugins and things
that aren't generic lookup plugins but look like them (vars_prompt
recently came up). Also a clear illustration of orthogonality: which
lookup plugins and other syntax can be combined with which modules, or
not.
As Ross puts it so aptly: these are my primary stumbling blocks that
the existing documentation doesn't solve adequately.
Finally, +1 for the 1-page documentation in addition to the current
many-page set.
And variable scoping too! Especially wrt to roles, vars/ vs default/, and hash_behaviour = merge. What isn't clear is when to expect a variable to be shadowed, unset, etc.
Also, how to pass values around without losing information, e.g. by stringifying booleans and data structures, or simply not being defined as expected. This is where my current pain points seem to lie.
I would love if there was a Wiki so it is not just Ansibleworks is responsible for documentation but also the community. the example i have in mind if not a wiki the php documentation where the PHP project writes something and you can see user contributions of how that should work, special use cases, or possible gotchas one need to be aware of .
also a section where infrastructure ssh/sudo configuration could effect Ansible configuration or the opposite (e.g. ANSIBLE_HOST_KEY_CHECKING, and the default connection type) . Or having all the gotchas in one place as us newbies these is where we have issues.
I would love if there was a Wiki so it is not just Ansibleworks is
responsible for documentation but also the community. the example i have in
mind if not a wiki the php documentation where the PHP project writes
something and you can see user contributions of how that should work,
special use cases, or possible gotchas one need to be aware of .
also a section where infrastructure ssh/sudo configuration could effect
Ansible configuration or the opposite (e.g. ANSIBLE_HOST_KEY_CHECKING, and
the default connection type) . Or having all the gotchas in one place as
us newbies these is where we have issues.
Thanks
Walid
Hey Walid,
I agree that its important to make it as easy as possible to contribute community content -- but in my personal experience, wikis ultimately require an expert to watch & moderate incoming stuff.
My experience is that github pull requests for more content provides a higher quality due to curated content, and uses an existing workflow that most developers are reasonably familiar with these days.
