Hi Walid,
The documentation is already an open source project.
This is better for us than a Wiki because it allows review of submissions in a better way.
If you would like to contribute to the docs, see the docsite/rst/latest directory in github.
We do have a technical FAQ and also take contributions on that part!
Beat me to the answer as usual 
Thanks.
The first pass is going to be a lot more restructuring based, and then we’re going to super-expand the cloud sections.
Didn’t think about the inventory scripts needing better docs (a casuality of watching all of this get built) so will definitely make sure we get that in there.
Might not be in the initial cut so don’t think it’s not coming if you don’t see it initially
One more thought on additional coverage; embedded python via jinja. Sometimes those little string transforms just allow you to create a cleaner playbook. Knowing that you can do {{ myvar.upper() }} or {{ ‘;’.join( myvar.split(‘.’) ) }} is pretty useful, and should be covered someplace.
Cheers
Ross
First, you are awesome for creating ansible in the first place and writing the docs in the first place. Your ongoing maintenance of the docs makes you double-awesome. Lots of open source projects die a slow death from a lack of docs.
Regarding structure, if there is any way to do transclude-type stuff, like in wikipedia, you could have it work several ways without lots of extra effort. For example, you could have a reference manual and a getting started guide where sections from the reference manual are pulled into the getting started guide and changes in the reference manual are reflected in the getting started guide. Then you could have content that currently resides in the the advanced playbooks stay there but also appear in a more easy to find location.
Basically, I’m suggesting that you should try and structure it in several different ways to accommodate different users and you should use transclusion (maybe via templating) to keep the work manageable and keep the different forms in sync.
Walid, Dave:
I like the documentation style provided by php.net where you have a top section that contains the standard text and a bottom section where developers post examples:
http://www.php.net/manual/en/language.variables.basics.php
I believe a moderator could restrict the posts to examples, workarounds, etc. But even this restriction would require some effort from the person(s) monitoring posts. If posts could be self-monitored by community members (rate up or down along with e-mailing the moderator to pull content or repost), that might make community contributions much more manageable.
The wiki format might be too open.
IMHO
-Leon
We’re not going to be building that section.
See previous posts about how people can contribute to the mainline docs, but I personally hate that about the PHP docs. A good document is complete it doesn’t have “but I have a question about X” at the bottom.
Thanks everybody who has given feedback so far, we’ve got enough
tl;dr A whole section early on about the variables including precedence (maybe with some pictures) and interpolation gotchas, etc.
I’ve only been doing ansible for a couple of weeks. I read the docs from getting started through best practices about a week ago and have been having great success with ansible.
I didn’t know of these inconsistencies with variable interpolation. These would be good to point out. I think a whole section about variables, early on in the docs, would be good. Somewhere in moving from command line examples + modules into playbooks, I wanted to know everything about how the variable context was built. I basically wanted to know what is in:
http://www.ansibleworks.com/docs/playbooks2.html#understanding-variable-precedence
I think this should maybe be more towards the introduction to playbooks rather than a note at the end. OTOH, I’ve had great intuitive success with variables, thus far. But, I’ve basically set all defaults in group_vars/all, set specifics in group_vars/foo and then set the couple of things which change with -e. I’ve not yet settled much into roles vars, vars in playbooks, vars_files.
+1 docs in git coming in with PRs.
A little section on configuration that exhausts the possibilities of what you can put in ansible.cfg, what can go into environment variables, how these are used and resolved and what the defaults are. Most of this can be gleaned from looking through constants.py. But, it would be more pleasant to refer to a section in the docs.
Quick update…
Much of the restructuring is now done, after about 12 hours of hammering on it. This is largely just a reorganization at this point.
You can browse the new page categories at https://github.com/ansible/ansible/tree/devel/docsite/latest/rst
I am still going through and adding missing links, fixing “see also” sections, and reviewing and editing each and every section before we push this.
This will be “phase 1”, future phases can/will focus on adding more examples and establishing more of a syntax reference, and adding some deeper explanations in various categories already mentioned.
Generally speaking, docs pull requests are quite welcome, though right now things are in a pretty high state of flux (and I don’t quite want to deal with conflicts as I haven’t got all of my ideas out yet), so I’d say hold off until later this week and then we’ll be ready for that.
I haven’t been reading the mailing list and just saw this. I’m very much agree that the documentation is sub-optimal. I’m sorry if these things have been mentioned in this thread but I don’t have the time to go through so here are a few thoughts:
Use syntax highlighting in the docs especially on the modules page where there are some large YAML configs. Yekyll can do that.
Provide a reference and a spec of the yaml syntax. (the section “YAML syntax” needs to much more verbose for beginners)
(5. Make the docs searchable.)
#1 is a big problem IMO. I’ve been learning GO and they’re doing a great job at that and always link to the source or doc or spec. They also have play.golang.org which is sweet, maybe play.ansibleworks.com??
HTH
Have enough feedback now, not interested in further replies.
Please consider this thread closed.