Category Archives: tools

Featured techpubs tools

Introducing Docs Like Code

I recently tweeted about a side project called Docs Like Code and wanted to tell you about it here. It’s a specifically-focused site where I can share my best practices and lessons learned about applying software dev techniques and tools to software documentation. I want to learn and teach at the same time as I keep exploring this space.

If you want to see a bit of how the site is put together, and how you can use GitHub to make web sites, join in. I have an email list you can join to get information as the site grows.

In the meantime, take a look at this quick less-than-five-minute look at how you can build Jekyll sites locally.

community tools

Reflecting and making: Inspiration in Ann Arbor this summer

I’ve written up my experiences at a leadership training class for OpenStack in Ann Arbor this summer. You can read more on the OpenStack blog.

We also had the opportunity to tour a maker space close to the training center, Ann Arbor’s Maker Space, and wow, it is neat. Comparable to a monthly gym membership model, they provide large woodworking and metalworking and industrial sewing and crafting machines for a daily or monthly fees or full memberships. Staff members are available for training, and each station comes with documentation. You can store large and small projects in progress so you don’t have to lug your work back and forth.

Tom Root, a Miami University graduate like me, started the space during the financial crisis in 2008. He has a vision of uniting a community of young people who need and want vocational and trade education with the experienced workers in the community who may have lost their traditional manufacturing jobs but have a lot of knowledge and experience to pass on. The Midwesterner in me knows that this type of collaborative space makes so much sense.

I was so inspired by the woodworking shop I decided to come home, buy some mesquite wood, and mimic some window treatments I’d seen on Fixer Upper for my own living room.



Here are some photos from our tour of the 11,000 square foot Ann Arbor Maker Space.

IMG_0972 IMG_0971 IMG_0978 IMG_0976

Why use GitHub as a Content Management System?

GitHub is a website that gives a user interface to source control. The tagline on the site is “Social Coding,” and I find that phrase to be an excellent summary of why GitHub is so useful for collaborative documentation. When writing for developers, write with developers, and believe me, developers are using GitHub for writing and coding. Like many tools, git and GitHub were created by fire—through a pressing need in 2005 for high-throughput and efficient source control management for the Linux kernel.

GitHub is the web interface, and git is the command-line tool that you use to copy files locally and track them. It’s cross-platform, so it works on Windows, Mac, and Linux operating systems. The biggest difference between git and other source control systems is that it merges files with a best guess rather than a “lock and checkout” model. The best guess for merging is often accurate but does require human inspection when the changes are too close to tell. The non-linear branching model means that you can experiment with many changes but still get back to a known state.

Here’s a brief vocabulary list for GitHub.

  • A repository is a collection of stored code or source documentation. For example, openstack-manuals.
  • A branch is an indicator of divergence from base. For example, the stable/liberty branch of openstack-manuals.
  • A commit is a point-in-time snapshot of a repository with changes. For example, this typo commit.
  • A fork is both an action and an object: forking is when you copy a repository, and a fork is a copy of a repository.
  • An issue in GitHub is a way to report defects, tasks, or feature requests. For example, an install article issue.
  • An organization in GitHub is a collection of repositories. For example, Rackerlabs contains Rackspace repos.
  • A pull request is a comparison of edits to see if the reviewing team wants to accept those changes into the main repository. For example, this pull request for a Rackspace page on

GitHub has some offerings that cover a couple of different use cases. Private repositories on the public site are about $7/month as a subscription and let you mark a repository as private and only invite trusted collaborators. GitHub also has an enterprise offering where the entire website is hosted where you want it and branded with your domain name. With GitHub Enterprise, you can ensure only company employees can access the source and collaborate with each other. Look up more options and pricing information on

Why use GitHub instead of a traditional CMS for docs?

When you are collaborating with technical people on distributed projects, often they are already accustomed to a GitHub workflow. So applying that workflow to technical documentation related to the project is a natural fit. Also, since GitHub has flexible review processes and prioritizes continuous integration, applying those benefits to documentation reviews and builds gives you the benefit of content management while bridging to sharing knowledge with subject matter experts. GitHub is a great match for when developers are writing documentation in source control. GitHub works well when a project is so large or distributed that no one person can know enough to write the documentation for the project. While GitHub is often associated with source control, the collaborative aspects go well beyond the traditional source control and CMS models.

In OpenStack, we have documentation workflows that mimic our code collaboration. We post patches for people to review, we review each other’s patches (similar to a pull request on GitHub), and we have build and test automation for every doc patch. The idea is to use the collaboration available in the GitHub pull request workflow for docs as well as code. We’re all responsible for relevant and accurate documentation for about 25 OpenStack projects written in Python across 130 git repositories, so let’s work together.

I do get questions from writers who are getting started with these types of workflows, so I wanted to bring together some of the best practices we’ve found, and find more. Here are two articles that serve the purpose along with a slide deck from a presentation I gave this year.


State of the Migration to Sphinx/RST

I wanted to document the migration journey while we are in the middle of it. Last week the OpenStack Super User site did a great article about the migration, How you can help with the documentation site refresh. We talked about the reasons for it: enable more contributors, offer simpler markup, be more Pythonic.

And more Pythonic we are. Let’s dig into what’s going on with the migration, what we’ve learned, and what we still have to learn.

Migration process

We’re nearly done with patches to review converted End User Guide files, but just a few Admin User Guide files are complete. Sign up on the OpenStack wiki at Documentation/Migrate. I’ve figured out how to include certain files in a build conditionally with an extension we’ll call “scope” for now. Using (and abusing) the meta information by putting a special directive in a file meant for admin-only lets us “tag” certain files for inclusion and build output with those files included.

New content page design
New content page design

How to build locally

We have always had tox jobs for building and testing the docs. The newest one runs the sphinx-build command for the end user guide.

If you don’t want to use tox, install these prereqs locally to test only the build:

pip install sphinx; pip install openstackdocstheme

Next, switch to the directory containing a and run:

sphinx-build /path/to/source/ path/to/build/

This command builds html output by default.

In troubleshooting some markup I found that the sphinx-build command does not give as much information about the markup as python build_sphinx does. So I will test a switch with a file as well as a file for each guide in the openstack-manuals repo.

To build locally with tox, follow the instructions on the wiki page. Building with tox is preferred as that matches our gate tests for patches. Feel free to ask for help in #openstack-doc on freenode IRC if you run into errors. We have tested the instructions on Linux, Mac, and Windows.

Conventions and editing RST markup

Docs tools guru Andreas Jaeger already had a head start in adding RST markup conventions to our Documentation/Markup_conventions wiki page on the OpenStack wiki. I’m finding that there are some types of content, such as extra information embedded in a list item like a table, that just can’t come over in its current state. I’m still working through these questions and it seems as though numbered lists can’t have much more than single list items. Anyone with info, please let us know if these are possible:

  • How to get numbered list continuation to work when you have a table after a #. list item?
  • How to get numbered list continuation to work when you have a bulleted list between #. list items?
  • How to get get embedded .. note: directives to work between numbered list items?

Matt Kassawara asked if there is a side-by-side editor for RST like there is for Markdown, and so far there is not, but the Sphinx development mailing list has a thread about what authors currently do as well as what they’d like to build.


We still need output bugs fixed. To me, the top priorities are:

  1. Sphinx template needs precise “Log a doc bug” link created on-demand similar to current functionality
  2. Sphinx openstackdocstheme needs to be tested for the translation toolchain
  3. Sphinx openstackdocstheme doesn’t style admonitions (note, warning, important) correctly
  4. Plus sign appearing when numbered list followed by bulleted list

What I need to understand is what would compel us to update Sphinx itself, considering we don’t know when their next release is. We already pin to a beta version (1.3b) so perhaps  we can patch as needed and pin our version.


Generally, make sure your Python environment is installed and ready to go, and then use a virtualenv to be sure you have “corded off” the environment and know exactly what’s installed.

Use “pip freeze” to get a list of what is installed. If a package is missing, make sure you have access to pypi by running the pip install command with -vvv. Also if you’re not working in a virtualenv, ensure you run the install command with sudo on Mac or Linux.

If you’re working within a virtual machine like VirtualBox, you may find that networking settings change even if you go from wired to wireless or from one wireless network to another.

If the output looks strange to you, delete the /build/ directory then re-build. I suspect that CSS and JS files remain outdated or are not copied over every time.

Please log bugs in openstack-manuals with the tag “openstackdocstheme” if you see bugs in the output.

What this means for new guides in progress

The only new guide in progress is the Networking Guide and some of it’s in markdown, some of it’s in DocBook, and all of it can go to RST. We must get the translation toolchain working prior to publishing, and I’d prefer to get more output bugs fixed prior to switching any more guides.


API techpubs tools work

API Archaeology: Complexity and sizing of an interface

For both OpenStack and Rackspace cloud APIs, we use WADL, Web Application Description Language, to build an API reference listing for all REST API calls. In a previous post I discuss how the reference pages at are made with WADL source and a Maven plugin, clouddocs-maven-plugin. You can see the output for the Rackspace API reference page at, built with the same tool chain but different branding through CSS. I can discuss the tooling decision process in another post, but let’s talk about ongoing upkeep and maintenance of this type of API reference information.

In this post I want to dig beneath the surface to discover how complex these APIs are, how that complexity might translate into difficulty or time spent in documenting the interfaces, and discuss some of the ways you could assign the work for creating and maintaining reference information for APIs. In another post I said, start with a list. This post looks into what happens after you have a list and need more lists to know the shape and size of your API and its documentation needs.

Some of the complexity also lies in documenting the parameters and headers for each API. Just like unearthing the walls of an ancient structure, you can look at the various ways an API is put together by looking at the number of calls, the number of parameters on each call, whether there are headers on any given call, and how the calls are grouped and related. I’ve summarized some of that below for the comparison cultures, er, grouped APIs.



A call is defined as a GET PUT POST DELETE command sent to a resource. These are known as HTTP verbs.

A header is defined as an optional or required component of a HTTP request or response. There are plenty of standard headers, what I’m talking about here are the extra headers defined by the API you document specifically.

A parameter may be a query parameter or provide a way to filter the response for example. Parameters specify a varying part of the resource and your users need to know what parameters are available and what they can do with them.

Running the numbers

To get these numbers, I first built each reference site so that the WADL files can be built into a single folder, which lets me do a grep for a count.

So I cloned each repo, ran mvn clean generate-sources with in the api-ref directory, then ran this command from with in from within api-site/api-ref/target/docbkx/html

grep -c “rax:id” wadls/*.wadl | sort -n -k2 -t:

Then I imported the output from the command as a colon-delimited file to a spreadsheet to get these counts.
OpenStack API Reference Metrics
Number of Compute v2.0 calls:290
Number of Networking v2.0 calls:92
Number of Orchestration v1.0 calls:41
Total documented calls:755

Rackspace API Reference
Number of Cloud Files calls:21
Number of Compute v2.0 calls:70
Number of Networking v2.0 calls:18
Total documented calls:670

Here’s a breakdown for just a few of the OpenStack APIs header and parameter counts.
Object Storage API Parameters: 12, Headers: 75
Volume API Parameters: 23 Headers: 0
Compute core API Parameters: 69 Headers: 1

Other metrics

We track doc bugs for the OpenStack API reference in Launchpad with the openstack-api-site project. There are nearly 200 doc bugs logged against the API Reference right now.

The three APIs with the most calls for Rackspace are Monitoring, Email & Apps, and Load Balancers, all of which are not OpenStack APIs. So a full two-thirds of Rackspace calls are not OpenStack-sourced. However, this means that a full third of Rackspace calls are identical to OpenStack.

What are some of the differences between OpenStack and Rackspace?
Extensions are complete in OpenStack; Rackspace only implements a handful of extensions.

Internal (admin-only) and external (user) calls are documented in OpenStack; Rackspace API Ref only documents external calls.

Rackspace has paid API writers and accepts pull requests on Github; OpenStack docs are written by writers and developers in the community (often with corporate sponsors) using the OpenStack gerrit process.


So that’s a lot of numbers, but what’s your point? My point is that making lists helps you determine the size and complexity of documenting multiple APIs. Not all companies or projects will have more than one API to document, but as we move towards more application interfaces for more business reasons, I believe that writers and developers need to get really accurate in their estimations of just how much time to allocate to document their APIs and do it well. Since these estimates are for API reference information only, don’t fail to also estimate time to write and maintain viable, tested example code as well. That’s a post for another day, thanks for reading about the complexity and comparison of OpenStack and Rackspace cloud APIs.

community techpubs tools

Tearing down obstacles to OpenStack documentation contributions

Rip. Shred. Tear. Let’s gather up the obstacles to documentation contribution and tear them down one by one. I’ve designed a survey with the help of the OpenStack docs team to determine blockers for docs contributions. If you’ve contributed to OpenStack, please fill it out here:

I want to use this survey to avoid shouting opinions and instead make sure we gather data first. This survey helps us find the biggest barriers so that we can build the best collaboration systems for documentation on OpenStack. Here are the obstacles culled from discussions in the community:

  • The git/gerrit workflow isn’t in my normal work environment
  • The DocBook and WADL (XML source) tools are not in my normal work environment
  • My team or manager doesn’t value documentation so we don’t make time for it
  • Every time I want to contribute to docs, I can’t figure out where to put the information I know
  • When I’ve tried to patch documentation, the review process was difficult or took too long
  • When I’ve contributed to docs, developers changed things without concern for docs, so my efforts were wasted
  • Testing doc patches requires an OpenStack environment I don’t have set up or access to in a lab
  • I think someone else should write the documentation, not me
  • I would only contribute documentation if I were paid to do so

Based on the input from the survey, I want to gather requirements for doc collaboration.

We have different docs for different audiences:

  • cross-project docs for deploy/install/config: openstack-manuals
  • API docs references, standards: api-site and others

These are written with the git/gerrit method. I want to talk about standing up a new docs site that serves our requirements:

Solution must be completely open source
Content must be available online
Content must be indexable by search engines
Content must be searchable
Content should be easily cross-linked by topic and type (priority:low)
Enable comments, ratings, and analytics (or integration) (priority:low)

Readers must get versions of technical content specific to version of product
Modular authoring of content
Graphic and text content should be stored as files, not in a database
Consumers must get technical content in PDF, html, video, audio
Workflow for review and approval prior to publishing content

Content must be re-usable across authors and personas (Single source)
Must support many content authors with multiple authoring tools
Existing content must migrate smoothly
All content versions need to be comparable (diff) across versions
Content must be organizationally segregated based on user personas
Draft content must be reviewable in HTML
Link maintenance – Links must update with little manual maintenance to avoid broken links and link validation

Please take the survey and make your voice heard! Also please join us at a cross-project session at the OpenStack Summit to discuss doc contributions. We’ll go over the results there. The survey is open until the first week of May.

community content strategy techpubs tools

A Few of my Favorite Things for 2013


This year has been filled with interesting finds, discoveries, and productivity. Plus oxford commas! Here are my favorite things for 2013.

The Hunger Games trilogy, because it’s like a window into a mind of a smart writer who writes with purpose.

The Documentation chapter of the Developer Support Handbook has to be one of my very favorite things I discovered this year. I’m on the Developer Relations Group team at Rackspace and this is a great handbook for all of our team.

Animated GIFs, pronounced jifs, am I right? OpenStack Reactions cracks me up.

Grace Hopper Conference by the Anita Borg Institute, especially the Open Source day, and the GNOME Outreach Program for Women which OpenStack started participating in this year. Women in technology are my favorite!

The Houzz App on my Android tablet for eye candy while messy remodeling was actually happening. Plus it’s the best content remix site I’ve seen in a while, more targeted than Pinterest.

Photo kids

Probably the best photo of my kids this year, I make it a favorite because at their ages it’s difficult to get one of the both of them.

OpenStack Docs Boot Camp

OpenStack Security Guide book sprint, read it at


OpenStack Operations Guide book sprint, now an O’Reilly edition, read it at

How about you? What are some of your favorite things from this past year?

community tools work

PyLadies Austin OpenStack Presentation

The lovely and talented Barbara Shaurette invited me to speak to the PyLadies Austin chapter last night and I readily accepted! I was quite nervous as I had not one but two demos to run, one of which involved running actual Python code. I took Ed Leafe’s Pyrax tutorial and got it running with my Rackspace Cloud credentials, and poof, I can spin up cloud servers with Python!

Here’s the presentation, OpenStack How To – PyLadies ATX, with step-by-step how-to instructions for using OpenStack and making OpenStack. Feel free to point out any corrections and ask any questions here or on SlideShare. I want to keep improving my demos and presentations.

All the attendees got a card worth $100 credit towards Rackspace Cloud goodness, so I hope they use their newfound cloud power with gusto. Thanks Barbara and PyLadies Austin!

content strategy techpubs tools writing

Documentation as Conversation with CSS

Three types of speech balloons: speech, thought, scream.

I love to explore new ways of conveying technical information, and I’m interested in documentation as conversation. Last year I wanted to convey a “side note” on each page of a Sphinx site, as if the page were talking to you. I needed to let people know that there are additional documentation pages available. So, I went looking for a CSS design that would let me put the note into a particular tag and style as I like. I found it at Pure CSS speech bubbles. The humorous part was figuring out what speech bubbles are also called so I could do a Google search. Speech balloons? Dialog balloons? Word balloons? I never did come up with balloon but somehow found bubble.

For Sphinx sites, which are built from RST (ReStructuredText), you use a layout.html file in a _theme folder with your .rst source files. This templating is explained in more detail on the Sphinx documentation site at In this case, the p tag is styled with css classes. Here’s what the HTML looks like:

<p class="triangle-border right">
Psst... hey. You're reading the latest content, 
but it's for the Block Storage project only. 
You can read <a href="">
all OpenStack docs</a> too.</p>

The CSS is much more involved, giving borders and rounded edges and putting that little triangle to indicate the speech. You can see it embedded in the Sphinx framework at tweaks.css. You can select a border color to match the rest of your page. Here’s the resulting HTML output. Speech bubble example

You may have seen the trend towards comic books or comics to explain technical topics, such as the one for Google Chrome at There are drawn comic characters explaining the browser design considerations throughout, with speech bubbles, hand waving, folded arms, lots of body language expressed throughout. This simple side bar doesn’t attempt that level of engaging content, but it’s a playful way to let people know there’s more than a single page for OpenStack docs. What do you think about such techniques, are they playful and harmless or sloppy and annoying?

techpubs tools writing

Who Wrote OpenStack Grizzly Docs?

Sneaking a peek at the numbers for documentation along with the code should show us pointers about docs keeping up with code. As I suspected, there were about three major contributors to the operations manuals that span all the projects, and about three major contributors to the API docs. Also not a big surprise, I am the major contributor to both. My spidey sense felt it but I had a real gut check with the actual data.


What’s difficult about this data analysis at this time is that we still need to release the docs even while we plan for the next six months. What I really want to do is look at the past six months and all the amazing work and accomplishments we have seen. The growth has been great and the fantastic feat of the Operations Guide really topped off my year. But we are still lacking enough strong doc contributors to keep up with the pace of code growth.

First, let’s look at the OpenStack code analyzes. The last six months showed 517 contributors. For example, Object Storage grew their new contributors by over 35 people which is probably doubling the involvement. Our Infrastructure team continues to raise the bar for helping us slam in more and more bits as fast as our little cloud servers can slam them. Here’s Monty Taylor’s report:

OpenStack code patches

                        Essex   Folsom  Grizzly
Patches Uploaded        11036   17986   29308
Changes Created         5137    5990    12721
Changes Landed          4235    4978    10561
Avg patches per Change  2.6     3.6     2.7
Landing Percentage      82%     83%     83%

What I want to do here is provide similar data that shows the growth of the project relative to the docs. I’m using the openstack-gitdm project to run the numbers for the documentation repos. There are eight in total but I’m just going to look at the top two, openstack-manuals and api-site. The openstack-manuals repository holds the install, configuration, adminstration, high availability, and operations guide. The api-site repository holds the building blocks for the API reference page, the API Quick Start, and other API guides (but not the API specs).

Here’s a listing of all the OpenStack doc repositories:
openstack/openstack-manuals – for operators and deployers,
openstack/api-site – for API consumers,

These are the types of statistics I want to know about doc contributions.
Number of doc contributors: 79. This is a great value.
Number of new doc contributors: 27. I like this from a growth standpoint.
Number of doc contributions: 512. There were 435 doc changes within openstack-manuals during the grizzly release, and 429 during the folsom release. Compared to over 12,000 code changes I instinctively know this wasn’t enough doc update. While we do have a good base set of docs, they are getting a bit crufty and we want to address that in the Havana release.

Number of employers: 49 (up from 37 last release). This is a high number. The highest doc contributing employer is Rackspace during the Grizzly release.

So, what about quality? The most bugs fixed by a doc contributor is 45 (well over half) by Tom Fifieldt. Tom is a great doc bug triage expert and I don’t know what we’d do without him.

How about what’s the top docs being read? The most read books are the Ubuntu Install and Deploy and the API Quick Start followed closely by the Identity 2.0 API Spec (wow that surprised me).

Here’s the reported data from openstack-gitdm. Thanks to Daniel Stangel for helping me retrieve this data. One hidden contributor is Jon Proulx, who wrote lots of the Operations Guide. Everett Toews also contributed a lot to the Operations Guide but won’t show up here. This omission leads me to suspect there may be other “ghosts” writing OpenStack docs, but I think the main point is, the top three shown below are far ahead of the fourth, fifth, and sixth-highest doc contributors.

Processed 435 csets from 79 developers
49 employers found
A total of 87457 lines added, 26085 removed (delta 61372)

Developers with the most changesets
Tom Fifield                 99 (22.8%)
annegentle                  86 (19.8%)
Lorin Hochstein             46 (10.6%)
Emilien Macchi              17 (6.0%)
atul jha                    11 (2.5%)
Mate Lakat                  10 (2.3%)
Diane Fleming                9 (2.1%)
dcramer                      8 (1.8%)
Aaron Rosen                  8 (1.8%)
gongysh                      6 (1.4%)
Ed Kern                      6 (1.4%)
Eduardo Patrocinio           6 (1.4%)
Alvaro Lopez Garcia          5 (1.1%)
Kurt Martin                  4 (0.9%)
Dan Wendlandt                4 (0.9%)
Razique Mahroua              4 (0.9%)
Gary Kotton                  4 (0.9%)
Dolph Mathews                4 (0.9%)
Christophe Sauthier          3 (0.7%)
Covers 80.459770% of changesets

Developers with the most changed lines
daisy-ycguo               37578 (39.9%)
Diane Fleming             19381 (20.6%)
annegentle                7624 (8.1%)
Tom Fifield               3126 (3.3%)
Lorin Hochstein           2757 (2.9%)
John Griffith             2390 (2.5%)
gongysh                   2169 (2.3%)
zhangchao010              2036 (2.2%)
Mate Lakat                1927 (2.0%)
Emilien Macchi            1684 (1.8%)
Navneet Singh              970 (1.0%)
Alvaro Lopez Garcia        647 (0.7%)
Brian Rosmaita             580 (0.6%)
dcramer                    554 (0.6%)
Dan Wendlandt              472 (0.5%)
atul jha                   431 (0.5%)
EmilienM                   428 (0.5%)
Joe Topjian                411 (0.4%)
Eric Windisch              376 (0.4%)
Ed Kern                    341 (0.4%)

At the OpenStack Summit last week I started looking for data that will help us shape the scope for the documentation for the coming release. With the right scope, we can keep up with code. Right now the docs scope that DOES release with code is docs for Python developers only, at However it seems people want install docs more than anything around release time. We will release the docs next week, 4/30/13, and have basic install docs in review now. We’ll need to keep track of doc bugs once we release of course. What we want to do in addition to decreasing scope is to increase resources, so we are working with member companies to create and fill upstream OpenStack documentation positions at each member company. Other creative ideas are welcome of course. I find this creative resourcing fascinating and I’m not about to whine about keeping up. Rather, I want to keep rising to the challenge.