Category Archives: tools

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.

community techpubs tools work writing

How It’s Made: the OpenStack API Reference Page

Glad you asked! The site at is a collection of HTML pages, and one page has an especially interesting story about how it is built. The page provides a listing of all the API calls for all OpenStack APIs that contribute docs to the page. Currently the only API that is still a work in progress is the Networking API, but here’s a patch in review and they soon will be included also.

The page has a lot of Javascript and CSS, DocBook and XSLT, XML and JSON behind it, which enables a few cool features. One is the details button, which gives an expanded set of information after you click it. Another cool feature is the ability to display either XML or JSON examples for the request or response with a drop-down list, and you can choose which to show by default. I also like the in-page search, which is more powerful than just using the browser’s page search feature because it digs deeper into the descriptions, expands to show any hits on your keywords in required and optional parameters, and in the response and requests codes. It highlights the found terms after expanding. Another cool aspect of the page is that all the Compute API samples are tested against a gate using code in the nova repository. Tested samples have been added in meticulously by Laura Alves, an awesome doc intern, with additional thanks to Sean Dague and his cohorts poking nova developers during the last dev cycle to ensure we have test samples for all API calls.

I believe there’s a lot of value in a long listing of reference information for the OpenStack APIs, and I’m glad Joe Heck took the initiative to get a blueprint going for it. David Cramer, Joe Savak, and Thu Doan at Rackspace took the blueprint and made it a reality with the Maven plugin at clouddocs-maven-plugin. The original goal of the page was to provide an all-in-one listing of all the API calls you could make against OpenStack services. At the time there were 3 or 4 services. Now we could potentially have 9 services with both admin-level API calls and end-user API calls, not to mention the extensions across 3 or 4 of the 9 services. So we are revisiting the all-in-one design of the page. Another aspect of the page is that it’s the only place to get documentation for the Compute extensions right now and the only site with tested examples without spelunking the code itself.

So, how’s it made? The basic building blocks of the page are:

  • WADL files – Web Application Description Language, a proposed Wc3 standard in XML used for describing REST APIs, read all about it in the specification at Here’s an example with the Image API 1.0 WADL.
  • XML files – Sample requests and expected responses. For Compute, these are copied right from the repository and each code submission that has an API piece must contian templates that build the example. Here’s a sample file: userdata-post-req.xml.
  • JSON files – Sample requests and expected responses. Here’s a sample file: userdata-post-req.json.
  • DocBook file – DocBook is an established documentation XML standard. Here it’s used as overarching XML organizing file, you can see it at api-ref.xml.

With these building blocks assembled in the openstack/api-site repository, you must also have a pom.xml to make the Maven plugin build the resulting api-ref.html page. The pom.xml is called by a Jenkins job maintained in the openstack-infra/config repository in a .yaml file. To build it yourself locally, install Maven and then do:

git clone git://
cd api-site/api-ref
mvn clean generate-sources

Wait a while (maybe even 15 minutes first run) for the build to get all the dependencies it needs, then when you see BUILD SUCCESS, open the api-ref.html file in the target/dockbkx/html/ directory and revel in all the features listed above. If you want to submit a change, use the Gerrit workflow all the OpenStack projects use.

The backlog of bugs for this page is maintained at If you see a mistake or want to ask for a addition, feel free to log a bug there. Laura Alves, our GNOME Outreach Program for Women intern, did an excellent job this past three months maintaining the page. My fellow Racker Diane Fleming is currently doing doc bug triage and fixing for the page as well. Future plans include adding a navigation layer on top of the page so it’s not one long page, but lets you pick the API for the service you’re interested in. With the additional APIs and new versions, we definitely want to keep updating the design as the APIs themselves grow and mature. Feel free to join in the API fun.

api-refhtml page

techpubs tools writing

Open Help Conference 2012 Introduces igor

I’m at the Open Help Conference in Cincinnati this weekend. Yesterday Florian Nadge from RedHat gave a lovely talk about Writing for Translation.

Next up was Warren Block, longtime FreeBSD contributor, Automating Documentation Proofreading

What tests of your doc can be automated? Many. He culled common misspellings from bug reports and his own knowledge. He used the AP style guide and wrote an algorithm from it. He found some word usages that usually need re-writing. Then he bundled it all up in a perl program called igor.

Writing Style Tests

you and your – look for too many uses
should – try to take out wishy-washy language if the user MUST do so
obviously and needless to say – can be offensive to many people, sounds like you’re talking down to the reader
starting too many sentences with “the”
e.g. and i.e. – nearly always used improperly with incorrect commas, also typically used backwards “for example” and “that is”
No examples – man pages require examples so you can flag on the lack of them

DocBook Tests

Rules different for different projects, but you could write the rules to put in a check for these.

  • Whitespace
  • Indentation
  • Tag usage style
  • Title capitalization – Uses AP Style Guide.

Program is called, igor, the lab assistant. Written in perl. Regular expressions all the way down. You can use the “ports” system:
or get it at:

Usage: igor -R -y chapter.sgml | less -RS

On my Mac, which has perl 5.12 already installed, I downloaded the files from that directory, rename the igor file to, and ran it against an OpenStack source file with this command:

perl -w -R -y ~/src/openstack-manuals/doc/src/docbkx/openstack-compute-admin/computescheduler.xml

This is what I get in return:

computescheduler.xml style check:
"you" used 2 times
"your" used 3 times
"You" and "your" are informal and subjective.
Try to be formal and objective: "the file" rather than "your file".
"should" used 3 times
Use "should" sparingly, it is feeble.
Try to be imperative: "do this" rather than "you should do this".
"the following" used 2 times
If something is following, the reader can see it without being told.
"e.g." used 2 times
"E.g." (Latin "exempli gratia") means "for example" and is mostly
used in academic and scientific writing.  Consider replacing with the
more common English words.  Both forms are usually followed by a
comma for a verbal pause:  "e.g., a b c" or "for example, a b c"
"i.e." used 5 times
"I.e." (Latin "id est") means "that is" and is mostly used in academic
and scientific writing.  Consider replacing with the more common
English words.  Both forms are usually followed by a comma for
a verbal pause:  "i.e., a b c" or "that is, a b c"

I can take this set of “critiques” for this chapter, revise the chapter, and add quality and consistency! Pretty nifty.

What’s New in Conversation and Community?

Conversation and Community 2nd Edition Cover

Love this new cover, both photos are Creative Commons licensed once again. Let’s look between the covers though!

While thinking about the second edition and how three years had passed, I was pleasantly surprised that we could get to the three year mark with the book’s content remaining relevant and accurate. Seems nearly impossible on such a fast-moving topic as the social web. Yet while looking through the tools chapter to update it, we mostly tested URLs and looked at the categories. Surprise, nearly all example tools are still relevant and useful to technical documentation. Not all the exact examples still existed, but that was just interesting to revisit.

Next, I examined the book for three areas of improvement – organization, content updates and additions based on my most recent experiments and experiences with OpenStack at Rackspace.


With the tools being so much more a part of every  day life and work now, I have moved the “Concepts and Tools of the Social Web” chapter to become an appendix. It also lets readers go right into “Defining a Writer’s Role with the Social Web” where I walk through a strategic approach to the social web. I also moved an entire section about managing community methods into a new chapter titled “Analyzing and Measuring Web Techniques” to expand on the management practices and business value tie-ins.


Some of the best additions to the book are interviews with practitioners I’ve met over the years who are doing community-based documentation already. It’s a balanced mix of open source communities and corporations using community to add value to their offerings. These are scattered throughout the book. I answered these same questions as well about how my current work is structured.

Based on my observations with documentation comments over the last year and a half, I added plenty of commentary and guidance to “Commenting and Connecting with Users.” Selecting and implementing a commenting system is chockful of requirements and guardrails for comments included on every page of your documentation. I also give an example of how to process comments daily, weekly, and moderate comments.

I added some additional information to the wikis chapter based on my recent experience with a Google Summer of Code documentation summit, comparing and contrasting “typical” wiki writing to planned writing. Many wikis have become web content management systems that encourage collaboration, so while I continue to address wikis in a separate chapter, the community and conversation building remains at the heart of my book. For wiki-specific tactics using Confluence, I’d highly recommend Sarah Maddox’s book, Confluence, Tech Comm, Chocolate, which I reviewed previously.

I added a chapter about content strategy for community documentation. I’m definitely sensing a strategic specialty opening up right now, and want to keep exploring it through the lens of content strategy. There’s a great case study included as well about Autodesk and their learning communities. An interview with Victor Solano with Scot Abel lets you “explore how the software giant has leveraged the power of the crowd, software standards, and content management to meet the fast-changing needs of its customers.” I found it thought-provoking and inspiring.

If anyone would like a signed first edition, please let me know by sending an email to annegentle at justwriteclick dot com. We’ll work out shipping and payment (Paypal or check-in-the-mail) with the few remaining copies I have!

techpubs tools work writing

From Cement to Spandex – Making PDF and ePub

Which statement is true:

“PDFs are like cement.”


“Gentlemen prefer PDF.”

Turns out both are true! See my recent OpenStack blog entry, Hacking on Ebooks, for more context and attributions for those statements.

We recently held a hackathon which I blogged about earlier to discuss the prep work for creating epub from DocBook XML source for the OpenStack and Rackspace manuals. We had a very successful day of hacking on 11/11/11. A team of about seven writers, testers, and developers worked all day to try to make epub files. And sure enough, we did it!

Our list of bugs matches up with what others have noted about difficulties making ebooks, such as sizing images properly and enabling tables that scale when zooming in or out or being displayed on a small smartphone or a larger tablet screen. Turns out, many “pro” epub creators turn all the tables into images to avoid the sizing problem. We also noticed the problem with mobi output putting a new line for each list item, and I haven’t gotten the fix working yet. We’re starting with the OpenStack Starter Guide available as an epub download and automated outputting epub for that book. We’re checking out the downloads to see whether there’s interest and we’ll go from there!

tools work writing

DocBook, ePub, Hackathon, What More Could You Ask For?

This Friday, on 11/11/11, the Austin Rackspace office is holding a Hackathon. The projects range from “fix the arcade game” to “install notification system to indicate availability of the men’s room” to my pet hack project, “create epub output for Rackspace and OpenStack manuals.”

Here’s a short introduction about making epubs from the FLOSS Manuals book, E-Book Enlightenment.

Of all the formats for e-books only EPUB combines small file sizes with the ability to do formatted text and illustrations. An EPUB is like a website contained in a Zip file, with a Table of Contents attached. It is also in one important way different from a website. A website is made with HTML (usually) but an EPUB is made with XHTML.

The difference is small but crucial. HTML is meant to be forgiving. If you make a web page you can leave out some tags, fail to close tags, or close tags in a different order than you opened them in. A web browser is supposed to forgive that, as much as possible. XHTML, on the other hand, is like HTML that is not forgiving. You can’t leave out a tag or put in a tag where the XHTML browser does not expect it. If an XHTML browser discovers an error in your page it can simply refuse to display it.

The end result is that an XHTML browser is easier to make than an HTML browser. A lot easier. It does put a burden on the e-book author to get his tags right, but in practice you’ll never create an XHTML file by hand.

With automation in mind, we’re going to use our existing toolchain to make the epub. Earlier this year, Robert Nagle, a tech writer in Houston, wrote up his findings about Docbook and epub. He writes for the Teleread website. What’s interesting to me is that he wrote up this blog post last year (11/7/10) about his findings while making epub from DocBook source and this past September said his next priority is moving his workflow to Oxygen + Ant + DocBook. David Cramer, our Doc Build Developer, has briefly tested the Maven-based toolchain by simply adding the goal generate-epub to a pom.xml file and building. That method did not copy over images. Then he tried building as part of the clouddocs plugin and received an error. We’ll start our debugging with the toolset, but we’ll also need debugging of our DocBook source as well.

Most of the “success” of the hack fest will be having fun and not sweating the small stuff. To me, we can call it done when we have epub examples for one OpenStack book and one Rackspace book that you can page through and read on a plane. Images should behave within reason, tables should be readable, and notes should be designated as such. Beyond those criteria, we’re exceeding expectations.

In case you’re curious about our tool chain for OpenStack docs, I have instructions on the OpenStack wiki. If you’re on a Mac or Linux machine, here are the quick steps for getting started with the tool chain for the openstack-manuals project:

1. First install the Apache Maven project.
With Macports already installed on a Mac, you can do this:

sudo port install maven2
or on Ubuntu

sudo apt-get install maven2

2. Install Git by referring to Mac or Linux instructions.

3. Get (git it? Ha!) and then build the docs with these commands:

git clone
cd compute-api/openstack-compute-api-1.1
mvn clean generate-sources

You will see a /target directory containing HTML and PDF output. Perhaps after Friday, you’ll also see epub output, who knows? While Friday’s Hackathon is for Austin Rackers, I’m happy to share our experiences here. Here’s hoping the OpenStack community will benefit from our hacking.