Sam Wills

Author Archives: Sam Wills

Docs Spotlight: Keeping the FM in RTFM

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 Continue reading

Docs Spotlight: Keeping the FM in RTFM

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 Continue reading

Docs Spotlight: Tower API Guide

blog-header-docspotlight

As you may already know, Ansible Tower 2.3.0's release offers a bundled installer for Red Hat Enterprise Linux and CentOS systems. This all-in-one installer contains everything you need to get Tower started in one bundle, including the bootstrapping of Ansible for you, if it is not already installed. If Ansible is already installed, ensure that it is the latest stable version before proceeding with your Tower installation.

In addition to other bug fixes and performance improvements, the documentation for the Tower 2.3.0 release also included a few updates.

The biggest update for the Tower Documentation Set hits the Tower API Guide

The REST API in Tower is browsable and simple to use, but you must be logged into your Tower instance to view the endpoints. Now, for the very first time, the Tower API endpoints have been included for easy review. 

For example, the Ping Endpoint, which is fairly simple as an example, includes the following information:

Ping_API_Endpoint

Another feature we are trying out for the Tower 2.3.0 Documentation Set is a new custom search.  At the bottom right of your browser screen, a new "search this site" button appears that scrolls the Continue reading

The Wait is Over. Tower 2.2 Docs are Live.

While prior versions of the Ansible Tower documentation focused on a single PDF, we've gone in a different direction for this release. You will still have all of the great content available from earlier releases, but in a documentation set comprised of guides focused on getting you going, installation and reference, administration, and more. I have to say that all of the outstanding documentation that was created for prior versions gave me a strong foundation to work with for this release and I'm grateful for the hard work put in before I joined the Ansible team.

With Ansible Tower 2.2, we are ensuring that access to HTML as well as PDF versions of the Tower documents are easily available from the docs website. Our Ansible Tower HTML documents also look and feel more similar to the Ansible  documentation available online that you've come to know and love. And, they've been indexed to help you find the information you need as quickly as possible.

Docs_Landing_Page

First, we're introducing Ansible Tower to new users with our Quick Installation and Quick Setup Guides. These manuals are geared toward getting Ansible Tower installed and setup to the point of running a simple playbook. They Continue reading