Documentation process improvement ideas?

Archives Ansible Developer
1

As I read through the Ansible docs, I’m constantly finding there are many small details missing. Some examples:

  • how is the current directory of the command module decided
  • what are the all the possible parameters to a task or a playbook (I don’t see these listed anywhere)
  • what language syntax applies where (e.g. {{ }} seems to work in some places, but not others (e.g. fails for me within, name: “…{{ }}…” )
  • a clear specification a of module interface (e.g. no x=y output is a failure, return codes are ignored, … )

I have an infinite list of small questions like this – as a new user I find I’m spending a lot of time trawling the google groups, SO or the docs, often after spending some hours experimenting to understand the detailed behavior of some small feature. Often, better documentation would have helped.

The documentation improvement process here: https://github.com/ansible/ansible/blob/devel/CONTRIBUTING.md
is problematic. As is often the case, the code contributors have no problem understanding the software, and so are unlikely to know where the need for improvement lies. New users OTOH, can do little with pull requests to help (because they don’t know how to improve the documentation).

So what would help?

  • a more wiki-like style of documentation where:
  • people can add questions/ask for clarification at the end of the page (how does X work)
  • original authors or other community members can respond or update the documentation.

If this is difficult (say, because the docs are auto-generated from code), then perhaps:

  • allow a comments and feedback section on each doc page
  • notify the original author (e.g. via a field held in community-submitted modules) and update the documentation held in git
  • (ideally) the comments could persist following documentation updates until deleted by the author.

The big benefit would be that it would enable the community to be a lot more efficient in:

  • discovering answers to problems. Searching the Internet for answers is a hit and miss (and very slow) process. Moving the questions to the documentation pages (where I search first) would allow existing questions and answers to be immediately found.
  • improving the documentation (by notifying authors where it is unclear, or allowing users to post questions or see response directly at the docs pages)

Any other ideas on how to improve things for new users?

  • Stu
2

Stu

Simply clone, update, and do a pull request. The site is in the main
project. https://github.com/ansible/ansible/tree/devel/docsite

3

If you cannot do the PR yourself, open a issue in github, bad documentation is a bug!

A developer will fix it.
​

4

I will say that’s welcome, but some of these things are also things we don’t want people to have to think about, and we’re less likely to document some of those things if we feel that way.

I do think an index pointing to all the keywords in Ansible to their respective hyperlinks, should you want to add that to the docs, would we SUPER AWESOME. Though some hyperlink anchors in the RST come up like #id100 meaning they do need permanent names on the anchors first (also fixes awesome).

Generally speaking on many “language syntax” types issues, we’d rather not have overly verbose explanations when we can make the app produce clear hints about how to correct problems and instead show examples of what does work, rather than examples of what not to do.

“As is often the case, the code contributors have no problem understanding the software, and so are unlikely to know where the need for improvement lies.”

As I’ve written nearly all of the documentation, I take some objection at this statement and we spend a lot of time on such things. I will say everyone learns very differently, so what works for someone and is too verbose or not verbose enough may be completely different for others. So what we do is try to strike a balance for people of different learning styles.

Having maintained quite a few Wikis over the years, that’s clearly not a good solution. Wikis are where good documentation goes to die. Our code review on docs has been HUGELY effective and people have made hundreds of contributions that are quickly merged, but we can still have a great discussion without turning it into a MMORPG :slight_smile:

In any event, documentation contributions are very welcome - we do have a vision for the nature of our docs, and get lots of positive comments on this, so don’t be TOO offended if we have preferences to how things are presented, but ideas are very very welcome.

The keyword index in particular - if comprehensive - would be a very nice contribution to the project.