Docs Spotlight: Keeping the FM in RTFM

December 21, 2015 by Sam Wills

blog-header-docspotlight

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.
Contributing to the Ansible documentation is pretty easy, whether you want to make a fork of the project and submit pull requests or report issues via GitHub. And if you ever have questions, you can always find someone to help point you in the right direction on IRC (freenode, #ansible-devel).  For more information on how to contribute as well as some guidelines, refer to:  And, for those of you who may be wondering about content translations, please know that localization is something we are discussing as well. At this time, however, we are concerned about the logistics of scale required to maintain up-to-date translations of the docs, including all of the module documentation. Recent conversations around translating bring up one main concern--the amount of time and dedication required to make sure the alternate language docs stay in sync with the main docs. Due to the fact that our docs are kept with the source code, any PR to update the docs would have to be applied to all of the alternate languages. 

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.
Share:

Topics:
Ansible, Docs


 

Sam Wills

Sandra A Wills (aka Sam & docschick) is the chief technical word wrangler (technical writer) at Ansible. After learning the art of great documentation and creating many installation manuals at Red Hat, Inc., Sandra went on to become a freelance editor, contract technical writer, and board member of her local arts council. She can be found on twitter at @unc_docschick and on Instagram at @docschick, otherwise you'll find her spending time with her family, crazy dogs, or making kiln-formed fused glass creations.


rss-icon  RSS Feed

Ansible Tower by Red Hat
Ansible In-Depth Whitepaper
ansiblefest brooklyn 2016
Learn About Ansible Tower