Crafting and maintaining high quality documentation is something we all know is very important. Reputable documentation is much more than the result of fantastic product or project management - especially when we're talking about community-driven documentation. Open source communities in particular like to reference "RTFM" (Read the Fine Manual, for the cleaner acronym explanation), but that's only helpful when the "Fine Manual" contains quality documentation. For projects like Ansible, it is our active users that make all the difference, and with their contributions and efforts we are able to help provide the great documentation that supports Ansible. But, that also comes with some caveats.
Many people contribute to open source projects so that they may "scratch their own itch." Whether this works well or creates clunky and cluttered code is not up for debate in this blog post, but how well it works in relation to open source documentation is debatable. Often contributions boil down to very bare bones coverage of a feature or implementation, other times the only contribution made is a typo fix. And while even the small fixes are helpful, these are not the contributions that make the docs great (better, yes, but not yet reaching that "FM" status we're hoping to achieve).
Answering questions and writing documentation, for users as well as for developers, are crucial activities. Simple projects may not require extensive or exhaustive content coverage—but documentation is still very necessary. Better documentation leads to fewer questions needing to be answered—but there are always questions that must be answered.
Ansible's success depends a great deal on the community supporting and expanding the documentation, and in them knowing the best way to help. Projects such as Ansible often have plans (or wish lists) for doc improvements. However, the community at large may not always be aware of what the core developers/maintainers may want nor do they always have the guidance they need to contribute (regarding what they could do, are able to do, or would be the most useful to do). While we do try our best to make our needs (and wants) publicly known, sometimes people miss an important forum or mailing-list post, or note on IRC.
So what is Ansible's open source project wishlist for docs as it gears up for finalizing the Ansible v2.0.0 release?
- Document other developing plugins (filter, connection, lookup, etc) just as modules are documented (*this is our biggest need at the moment*)
- Plugins need docs and the guidelines are very similar to that of modules
- Help ensure versioning for features, plugins, modules and other additions are correct
- If you know of something or have added something that is new to 2.0 but is not versioned, the documentation needs to be updated to ensure users don't end up in a bad place! New features should always be noted as "New in version 2.0" or "(added in v2.0)" for compatibility reasons and general sanity.
- I'd Like to Help with Documentation
- Homepage and documentation source for Ansible
- Ansible Extras Modules + You
- Module Checklist (great to keep in mind when documenting plugins)
That being said, for community members who want to take on such a project, we recommend forking the repo (if you have not already done so) and setting up an alternate directory for the translated docs. Please also include messaging in the introduction material stating that this is an unofficial translation, not localized by Ansible or Red Hat, Inc., and that it may not include the latest content additions or be completely in sync with the main project source. As we continue to discuss and plan for localization efforts on our end, we can look to use these localized forked projects in the future, once we're really able to support them. It's important that we do this right and make it maintainable, for our sanity as well as yours.