The state of Ansible's upstream documentation

Ansible documentation is changing fast to keep up with changes in the project. In this post, we’ll describe some of the biggest changes to the Ansible community docs, cover some ways you can help maintain and improve the docs, and look ahead at what we hope to accomplish over the next six to twelve months.

Red Hat Ansible Automation Platform, like other Red Hat products, adopts upstream innovations once they are ready for long-term support. The changes discussed in this post affect the latest upstream release, Ansible 2.10. The work we’re doing upstream, while not immediately included in Ansible Automation Platform, ultimately helps us improve the products to customers. We also have new downstream documentation for Automation Hub and Automation Services Catalog coming out with the upcoming release of the Red Hat Ansible Automation Platform 1.2.

Changes to docs - modules and more

New module docs URLs

With the full rollout of Ansible Content Collections in Ansible 2.10, we changed the URLs for module documentation to reflect the new structure of the Ansible code ecosystem. Module docs used to be in the "modules" section, but starting with Ansible 2.10 those pages are in a "collections" section.

For example, take a look at the URLs for the mysql_db module documentation in 2.9 and in 2.10. This change in the documentation reflects the changes in Ansible itself, with most modules and other plugins moving to collections in 2.10. As a result, we no longer have the old, enormous index page listing every module, and we no longer have the "modules by type" index pages (for example, the database modules index page or the cloud modules index page). We are exploring ways to reinstate index pages, since they are useful for locating individual modules quickly. 

Instead, the module documentation is now organized by collection. You don’t have to scroll through the long list of cloud providers to find the one you want to use. You can simply find the collection for your particular cloud provider on the collections index page and see all the documentation for related modules and other plug-ins there.

Redirects between 2.9 and 2.10

Because this is a major change, we’ve updated our webserver with redirects between the old-style module docs URLs in versions 2.9 and earlier and the new-style module docs URLs in version 2.10. This means you can still use any links you created when 2.9 or an earlier version was symlinked to "latest," and you can use the version-switcher to navigate among different versions of the same documentation page. However, with more than 6,000 redirect statements, we do expect some mistakes. If you find a broken redirect, please report it to the docs team! The best reporting method is on the #ansible-docs channel on freenode IRC.

Edit on GitHub links in transition

When all the modules were in a single repository, it was easy to embed an edit link into each HTML page. Now that modules have migrated to collections, it’s harder to know which repository contains the source code for any given page. We have disabled the "Edit on GitHub" links on the module documentation for now. If you see an error on a module page, you can still open a Pull Request to fix it, but it’s a little more complicated. From the module documentation, click through to the collection on Galaxy, then look for the "Repo" link to find the source code for that page and open a PR there. 

For example, from the mysql_user module page, follow the link to the community.mysql collection on Galaxy, then follow the "Repo" link there to the community.mysql source code on GitHub. The documentation for that module is included in the Python code in plugins/modules/mysql_user.py. 

We hope to reinstate the "Edit on GitHub" links in the documentation, at least for the major collections, in the future.

Docs for the "devel" version in transition

If you’re an experienced Ansible user, you may have read the ‘devel’ documentation to learn about unreleased features, especially if you were running Ansible from source. In the collections ecosystem, it’s harder to define the meaning of the "devel" docs than it used to be. The "devel" branch still includes core features under development, and we still produce documentation in the "devel" docs for those features as they mature. However, we don’t publish module docs in "devel." We cannot predict which versions of which collections (and thus which versions of which modules) will be included in the next distribution of community Ansible. 

Collections may add or deprecate modules and release many versions between one Ansible release and the next. There is no consistent standard for which collections documentation we should publish as part of the "devel" documentation. As the Ansible community continues the conversation about documentation, the scope of the "devel" documentation may evolve. We invite you to join the conversation. See the section on the Documentation Working Group below.

Documentation universe is expanding

Another big change in the Ansible documentation is the expanding overall scope. The Ansible community is growing every day, and the ecosystem now includes more tools and utilities than ever. Some community-maintained tools now have documentation hosted outside of docs.ansible.com. We have added new links to documentation for Ansible Lint and other tools, and we expect more expansion over the coming year.

Contributing to the Ansible documentation

We get a lot of compliments about the Ansible documentation (thanks!), but the documentation team can’t take all the credit—documentation is a community effort. Community members help the Ansible writers maintain, expand, and improve the documentation all the time. You can too—it’s a great way to get started contributing to Ansible.

If you’re looking for a good first project, search through the ansible/ansible GitHub issues for items with the labels "docs" and "easyfix." We try to identify at least one "easyfix" docs issue per month.

For help with the mechanics of contributing, take a look at our page about how to contribute to documentation.

Joining the Docs Working Group

If you support good documentation, or just like writing—or both—join the Ansible Documentation Working Group (aka DaWGs). We meet weekly on IRC (meetings scheduled in UTC time). We welcome questions, comments, ideas, and suggestions about both the content of the documentation and the documentation infrastructure. We have fun, and we get things done. See the Docs Working Group wiki page for details on meeting times and more, and feel free to add items to our 2020 meeting agenda (new agenda will start in January 2021).

Looking ahead to 2.11 and beyond

We plan to continue expanding and refining the Ansible documentation between now and AnsibleFest 2021. Here are three topics we want to focus on in the coming year:

• Expanding collections documentation: we want to develop documentation that shows how using related content within a collection (modules, roles, playbooks) can address complex use cases.

• Reorganizing content to focus on specific users: newcomers, experienced playbook authors, developers, and other types of Ansible users need different types of documentation; we want to reorganize and expand our existing documentation with this in mind. If you have thoughts, please add them to the docs etherpad.

• Documentation user survey: as part of the content reorganization, we’d like to hear from current users about what works well, what’s missing, and what would make the Ansible documentation even more awesome.

We look forward to working with the community, users, and customers on the Ansible documentation, and we hope you’ll join in!