Question: Role documentation, standards or best practices? about ansible-for-devops HOT 1 CLOSED

Great questions! This is actually something openly being discussed in the Ansible community, and the best place to focus your efforts (or at least hit the 'Subscribe' button) is here: ansible/proposals#19

For my own roles (example: geerlingguy.apache), I generally do the following:

• Add a few general comments and possibly an inline commented example or two inside defaults/main.yml
• Document every single variable (unless there's a block of similar variables that are self-explanatory) inside README.md (since this will be the welcoming text on the GitHub repo and on Galaxy for the role).
• Document at least one or two special use cases or examples in the README.md.
• Use the role tests (automated via Travis CI) as an extra 'in use' example or two—you'll be forced to always make sure these examples are correct/working if they're using Travis to build the role!

For really, really complicated roles, you could consider integrating with external docs, but I'd still store the actual docs in the project (I hate having a separate project/site to manage docs vs. the actual code...).

from ansible-for-devops.