Category Archives: writing

API techpubs writing

Modernizing technical documentation

As a technical leader at Rackspace during a docs modernization effort, I want to respond to Tom Johnson’s recent pointer to the developer docs site as an example of treating docs like code. Not just specifically for the “will it scale” questions, but for the questions I have fielded and continue to answer. Believe me, “Will it scale?” is the least of your concerns in a complex overhaul of attitudes, processes, tooling, and expectation setting.

I’m sure modern docs are not going to work for all projects and all people and all processes, but since I have first hand experience I thought it would be helpful to talk about it.

In case it helps, let’s describe the disruptions at the heart of the movement. You can see that outcomes matter.

Web delivery

If your old tooling cannot provide a great web experience, you need modernization. Traditional tech pubs tooling (Adobe, Madcap, Docbook) will struggle to develop wonderful, responsive websites that provide an amazing experience with documentation. There’s a natural struggle between artisanal hand-crafted documentation and producing tens of thousands of web pages that still offer a great experience despite the size of the site.

Continuous integration for documentation

When you treat docs like code, expect to enable more contributors, and when you enable more contributors, you need to automate builds and quality checks so your time is spent focused on doc outcomes, not running builds. Let the robots take care of builds and use tools that don’t require a seat license so that the writers aren’t having to build from their computers only. In OpenStack we can merge 50 changes a day in a single repository containing ten deliverables (web-delivered guides). We build draft copies with scripts for people to review the output online.

If traditional tech pubs tools product managers are reading, your next killer feature is Travis-ci job integration, Jenkins job enablement, and really any scripted way to build your output so that humans don’t have to click anything to build the docs.

Collaboration for documentation using code systems

Depending on your contributor base, you influence more people to respect the documentation and encourage contributors to improve the docs with you when the docs are in a code system. Across multiple repositories we deliver REST API documentation for almost 30 services. Some days there are over 100 changes that need to be reviewed for REST API docs.

Content management using code systems

I’ve presented and written about using code systems for documentation – git, GitHub, BitBucket, GitLab, and so on. See the resources section for a deep dive, but suffice it to say, I’m sold on using GitHub for your CMS and I know many other writers see it this way also.

Valid concerns

Here’s what you need to look out for and even embrace when the time comes:

Content sprawl: What goes where is a common question from contributors. Be ready with answers so your site doesn’t become a poor web experience. Have excellent navigation systems and way finders for readers.

Quality diminishing: Build a trusted set of reviewers and make sure they are equipped with a style guide and plenty of quality checks to keep in mind while reviewing. Be mindful and use metrics to ensure quality is a priority.

Loss of control: By enabling many contributors, you lose control of who writes what where. Be ready to trade control for many other benefits. I don’t have a control-based mindset so it’s natural for me to give up control in order to gain better outcomes.

Loss of choosing priorities: When you don’t personally manage and direct the teams of contributors, you don’t get to pick what is written first, second, or third. Or even if something is written at all. Have processes and systems in place for triaging doc issues, and create a culture where contributors have good judgement about what to work on first, second, and third.

Search and replace: When you need to make changes across multiple repositories and deliverables, be ready to up your bash scripting game or get help with it. Fortunately text manipulation is pretty powerful at the command line. Unfortunately some teams could be stuck with non-Linux-based systems and no tools to help with this problem.

Naming agreement: Unless you establish standards and have authority for naming certain parts of a project (plugin or plug-in as an example), you could waste time arguing about which name lands in the base.

Value diminishing: If you can’t train your writers to stop nitpicking grammar errors or capitalization consistency issues, and instead do technical reviews, you might have problems with a docs-like-code approach. In a docs-like-code world, be sure you know what is the most valuable contribution and make sure your teams can give those types of contributions.

In closing, you can see I’m a huge advocate for this approach to documentation. Please take a look at the resources I’ve been working on over the last few years to spread my enthusiasm and excitement for the modernization of technical documentation.

community techpubs work writing

Influencing community documentation contributions

After a week with leaders in the OpenStack community, taking leadership training, I’m inspired to write up ideas from Influencer: The New Science of Leading Change. For me, who needs to make the most out of community efforts, the idea that no one likes being told what to do was a familiar phrase. Rather, compel people to pick up your vision and add to it.

As an example, people often ask me, how do you motivate people to write documentation for open source projects? Or write for any software project?


Get details about the behavior you want to see

Using the framework this book offers, you first want to identify the behavior you want to see. Their examples often revolve around healthcare, such as hand washing. But you can get very specific about hand washing, such as where, when, and how. For documentation, you may say the behavior is “write” but I want to get more specific than that. Where should they write? Is the behavior “write a personal blog post?” Or is it “write in the official docs?”

Also, when should they write? Ideally as close to when the technical detail is still fresh as possible. The “when” could be at the end of a cycle when people are less distracted by feature additions. Or write documentation before the code is written and revise it often.

As for “how” do we want contributors to write, well, we may need to have templates and frameworks for the “how” — such as source formats, build jobs, and in which repo.

Looking at the behavior we want to see, getting super detailed about it, we find that we also want to encourage the behavior of code reviewers to read and review related docs.

Identify a crucial moment

Now, when a bit of code changes that makes a difference in the docs, that’s a crucial moment for influencing a particular behavior. The behavior we want to see is writing documentation while the code is fresh in your mind.CC Jonathan Cohen

Another crucial moment to engage is when a user first tries the feature; their fresh eyes may provide an update to the docs that others might not see. The “Edit on GitHub” feature of creating a pull request provides that outlet for fresh eyes to make a quick edit to the documentation.

So we have an idea of the behaviors we want to see, and a sense of when we want to see them. Now we can begin to ask what’s preventing the behavior.

Why don’t people contribute?

Let’s talk about: what’s painful about writing documentation? For example, if you speak English as a second language, it may be painful to write for others to review and the criticism might be more than you can bear. Kind, empathetic coaching, respect, and a culture of acceptance helps with this barrier.

Provide guidance and energy

Also, people associate boredom with docs. They look at a blank screen and can’t come up with words to describe their feature. They yawn and check their Twitter feed instead of writing docs. This pain point is where templates can help. People who don’t know what to write might need guidance, suggestions, or strict form-based templates.

Avoid context switches

It’s painful to have a doc tool set that’s extremely different from what you write code in — the context switch even to a web-based editor may be too big a barrier to jump over. Make the docs like code whenever you need to compel developers to write.

Get some influencers who believe in the vision

Without actual peer pressure that says “yes, we write the docs” developers may not create a culture that requires documentation. Start with the influencers in their peer group (which might not be you). For example, when a seed researcher wants to introduce a new hybrid seed corn, he goes straight to the local diner where the most experienced and influential farmer gets breakfast on Saturdays. It’s better to have the farmer in his pickup truck understand and believe in the benefit of changing to a new hybrid seed corn than for the researcher in his late-model Volvo.

Offer deliberate practice sessions

Also consider “deliberate practice” where you set aside time to get better at a skill. If the skill is writing, then have office hours or coaching sessions online, and at conferences make sure you can meet with people who want to become better writers to show them how to practice writing through drills, exercises, and with fun collaborative efforts such as doc sprints. Record a video or host an online hangout, showing all the steps for contributing deliberately and strategically.

Thanks to many coworkers who helped me discuss and think more about these ideas along the way. What are some additional ways to influence a desired outcome?

API work writing

Playing with technology

One of the greatest parts of my job is getting to learn, write, learn write in a never-ending pattern. I got to play with Docker Swarm on our Carina offering at Rackspace and wrote up this blog post. It’s a tutorial for using Carina to create a Jawbone App with node.js. You can see the results at



While looking for a data-driven REST API for that tutorial I came across Mashape, which has a marketplace for APIs. I found the “They Said So” quotes API while looking around for a word-nerdy data project next. I could also try out the Merriam-Webster Dictionary API and of course, the best word-nerd API there is, Wordnik. So much data, so little time.

I find it fascinating that these API marketplaces are popular. Mostly when I ask developers about the usefulness of a site like Mashape they can’t come up with a great use case. I wonder if discoverability of APIs is an important part of promoting and educating people about your API. I think that with more and more API definitions, there is more and more need for discoverability. And of course, documentation. Opportunity abounds.

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.

techpubs writing

Treat Docs like Code: Doc Bugs and Issues

This is a follow on to a post on about using git and GitHub for technical documentation. In the article, I discuss reviews and keeping up with contributions. This post talks about fixes and patches.


What about doc issues in GitHub, how do you get through all those?

In OpenStack, we document how to triage doc bugs, and that’s what you need to do in GitHub, is establish your process for incoming issues. Use Labels in GitHub to indicate the status and priority. Basically, you have to accept that it’s a doc bug, if it’s not a doc bug, ask for more information from the reporter. If you want to create labels for particular deliverables, like the API doc or end-user doc, you can further organize your doc issues. You will need to define priorities as well — what’s critical and must be fixed? What’s more “wishlist” and you’ll get to it when you can? If you use similar systems for both issues and pull requests you’ll have your work prioritized for you when you look at the GitHub backlog.

How can you encourage contributors to create a good pull request for docs?

The best answer for this is “documentation” but also great onboarding. Make sure someone’s first pull request is handled well with a personal touch. There’s a lot of coaching going on when you do reviews. Ensure that you’ve written up “What goes where” as this is often the hardest part of doc maintenance for a large body of work that already exists. This expansion problem is only getting harder in OpenStack as more projects are added. We’re having a lot of documentation sessions at the OpenStack Summit this week and we’d love to talk more about creating good doc patches.

One person I work with uses GitHub emojis every chance he gets when he reviews pull requests. I think that’s fun and sets a nice tone for reviews.

Nitpicking can be averted if you point to your style guide and conventions with a good orientation to a newcomer so that new contributors don’t get turned off by feeling nitpicked.

Have you heard of anyone who has combined GitHub with a different UI “top layer” to simplify the UI?

O’Reilly has done this with their Atlas platform. For reviews, the Gerrit UI has been extremely useful to a large collection of projects like OpenStack. There’s Penflip, which is a better frontend for writers than GitHub. The background story is great in that it offers anecdotes about GitHub being super successful for collaborative writing projects.

I think that GitHub itself is fine if your docs are treated like code. I think GitHub is great for technical writing, API documentation, and the like. Academic writers haven’t found GitHub that much of a match for their collaborative writing, see “The Limitations of GitHub for Writers” for example. It’s the actual terms that have to be adapted and adopted for GitHub to be a match for writers. For example, do you track doc bugs (issues) and write collaboratively with added content treated like software features? I say, yes!

If you just want simple markup like markdown for collaborative writing, check out Beegit. With git in the name I have to wonder if it’s git-backed, but couldn’t figure it out from a few minutes on their site. Looks promising but again, for treating docs like code, living and working with developers.

work writing

Be sure to read about my Stacker journey

The editors at The New Stack do great things with their articles, and mine is no exception! Be sure to read Anne Gentle: One Stacker’s Journey.

Even though I’ve lived in Austin, Texas, for over 14 years now, I tend to say I’m a midwesterner when asked. There are traits associated with the spirit of the midwest that I’ll always identify in myself: hard work, resource creativity and conservation, humility, and a sense of wonder at trends being set somewhere in the world. Read more…

blogging writing

More posts around the web

Seems like more and more I’m writing everywhere but here! I wanted to do a round-up of some of my writing around the web.

On the Rackspace Developer Blog: Austin Ladies Hackathon

This weekend was a blast, hacking with all women at Rackspace, and wow were the projects impressive. Here’s how it went.

Friday night we gathered at a restaurant, the Flying Saucer, to meet each other and start to form teams. I’d guessimate that 20 of the 30 participants showed up. I helped out by facilitating discussions for people to find teams, and I spent a lot of the night talking to complete newcomers about what a hackathon is like, what to expect, and especially how to learn at one. We also recruited for the upcoming NoSQL Mobile App Challenge ( (Read more …)

On the O’Reilly Radar blog: The book sprint: Not just for code any more

Do you really want a technical book for your project? Does your community need to provide more helpful docs to support even more users? Does your community have a lot of knowledge they need to get out of heads and into bits and bytes? Do you have a good mix of technical experts and technical writers and users who would enjoy each other’s company for a week of hard work?
If the answer is yes, then consider a book sprint. (Read more…)

On the blog: The Women of OpenStack talk outreach, education, and mentoring

In the open source world, a women-only event seems counter-intuitive. Yet I am finding reasons for such events the more I attend them.

At the OpenStack Summit, a twice-a-year event where OpenStack contributors get together to plan the next release, the Women of OpenStack group has set up events where we invite the women first. Men aren’t excluded, but our hope is to get more OpenStack women together. I can hardly capture the value of getting together with other women in OpenStack at the Summit, but here goes.(Read more…)

work writing

All About that OpenStack Operations Guide

I wrote a post on the O’Reilly Programming blog about our experiences writing a book in five days and revising it for publication as an O’Reilly book. The blog post is titled, The book sprint: Not just for code any more. This infographic summarizes the numbers quite well.
Many thanks to Racker Claudia Charbel for this infographic and for showing off the capabilities of!


community work writing

How to Build OpenStack Docs and Contributors through Community

I’m well past the three year mark, working on a new open source project that grows and grows every six months. I’ve been working closely with Diane Fleming at Rackspace to focus completely on upstream OpenStack. Upstream means that all of our documentation work goes to the open source project itself. So while Rackspace runs OpenStack in production and for our customers private clouds, Diane and I focus on documentation that helps any organization run and use OpenStack. We have put together an outline of what we do to make upstream OpenStack documentation better all the time.

Growth, scaling, and related challenges

When I started, there were just two projects with two APIs. Now we have 130 git repositories fostered by over twenty related programs. As you can imagine this scenario causes scaling difficulties but we are bravely making our way. Here are some of the challenges we have faced and what we’ve done to lessen the pain of coordinated, collaborative technical documentation in an open source community.


In the face of language and technical barriers, the OpenStack docs team used a combination of IRC meetings, documentation boot camp, Google hang-outs, a busy docs-team mailing list, and other methods to create a flourishing, global team of writers and technical contributors who have immensely improved the OpenStack docs in the last couple of years. The release that went out in Spring of 2013, three people wrote half of the docs. For the release that went out in Fall of 2013, seven people wrote half the docs. I can’t wait to see what our numbers are for the release going out next, on April 17th.

Team-building tools – the good, the bad, and the ugly

Here are some benefits and pitfalls of these tools:

  • IRC: Pros – clear agenda, follow-through week-to-week, global participation now that we have APAC and North American meetings. IRC meeting bogs enable an automated log of minutes. Cons: difficult to find agreeable time, no face-to-face, hard to introduce new topics.
  • Office hours: Seemed like a good idea but fell by the wayside, we did not have much attendance. As our team grows, people can stop by the IRC channel at any time to get one-on-one help.
  • Google Hangouts: With the video and voice enabled, it is nice to see each other’s faces without having to travel. Hard to find an agreeable time with the round-the-world team.
  • Boot camp: Extremely positive experience – spawned new ideas and new connections. Downside is the cost/time factor. We had great survey responses but decided we didn’t need one every six months.
  • Mailing list: Good way to resolve immediate issues and gather consensus as well as multiple view points.
  • Book sprints: Good way to get a needed book written and distributed. Not a good way to build ongoing community for maintenance, and in some ways you have to be careful not to build a book that no one else thinks they should contribute to. But community is just one part of good docs – this is a good complement to other efforts.

OpenStack docs – before and after

How have the docs changed due to team building?

  • Cleaner, more compact library. We did a huge refactor prior to the Boot Camp, which has made it easier to specify what types of content goes where.
  • Better writing. Professional technical writers have done an amazing job avoiding “frankendoc” — by editing, reviewing, and polishing with an agreed-upon style guide, we improve the actual writing to better serve readers and users.
  • Better technical content. In OpenStack, teams have core reviewers and most teams require two core reviewers must approve a change before it gets built to the published site. As we expand our reviewers (not just core but many reviewers) our docs have improved technically.
  • Better automation. By writing tools that scrape the code for docstrings we are able to keep up with fast-moving projects that release every six months.
  • Timing with releases. We carefully scope what documents are considered tied to a release. The Install Guides and Configuration Reference are the only two books built from a set release. All other documents are continuously published.

OpenStack contributors – before and after

How have the relationships among contributors and contributors’ roles changed due to team building?

  • Much greater communication among contributors – now we know each other on a more personal level, and feel more comfortable working together
  • Contributors have found where their strengths lie in the community. Some people are more tools and gear heads and build gates and tests and build tools. Some people are natural editors and review heavily with suggested edits. Some people are blue-sky visionaries. Some people are heads-down system administrators and architects. There’s a place for everyone, not just writers.

What’s to come?

We want to discuss revisions to our original vision openly. This blog post is a starting point, but we are listening on all available channels. At the OpenStack Summit in Atlanta in May, I want to collaborate on a request for proposals for a new front-end design for our documentation that can help us make changes to how docs are authored. I’d like to find out more about ways to enable non-CLA contributors to the docs. I have lots of ideas and look forward to working with this amazing group to improve our processes and results.


community techpubs work writing

OpenStack Operations Guide Mini Sprint


We held a two-day mini-sprint in Boston at the end of January to update the OpenStack Operations Guide. You may remember the first five-day sprint was in Austin in February 2013. This time, the sprint was shorter with fewer people in Boston and a few remote, but we had quite specific goals:

  • Update from Folsom to Havana (about a year’s worth of OpenStack features)
  • Roadmap discussion about nova-network and neutron, the two software-defined networking solutions implemented for OpenStack
  • Add upgrade instructions from grizzly to havana
  • Implement and test the use of parts to encapsulate chapters
  • Address editor comments from our developmental editor at O’Reilly
  • Add a reference architecture using RedHat Enterprise Linux and neutron for networking

Some quick wins for adding content were:

We added and updated content like mad during the two days:

The two toughest updates are still in progress, and our deadline for handover to O’Reilly is this Wednesday. The first tough nut to crack was getting agreement on adding an example architecture for Red Hat Enterprise Linux. We are nearly there, just a few more fixes to go, at The second is testing the upgrade process from grizzly to havana on both Ubuntu and RedHat Enterprise Linux. That’s still in progress at

The next steps for the O’Reilly edition are proofreading, copyediting, and indexing over the next six weeks or so. I’ll be keeping the O’Reilly edition in synch with our community-edited guide. As always, anyone in the OpenStack community can contribute to the Operations Guide using the steps on our wiki page. This guide follows the O’Reilly style guide rather than our established OpenStack documentation conventions. I’m looking forward to a great future for this guide and we’re all pretty happy with the results of the second mini-sprint.

Thanks to everyone making this a priority! Our host at MIT was Jon Proulx joined by Everett Toews who braved airport layovers and snow, and Tom Fifield who wrote the most patches despite a complete lack of sleep. Joe Topjian worked on edits for months leading up and has been tireless in making sure our integrity and truth lives on through this guide. Thanks too to the the hard working developmental editor at O’Reilly who offered lunch in Boston, Brian Anderson, joined by Andy Oram. David Cramer got DocBook parts working for us in time for the sprint. Summer Long worked long and hard on the example architecture for RedHat. Our remote reviewers Matt Kassawara, Andreas Jaeger, and Steve Gordon were so valuable during the process and ongoing. Shilla Saebi gave some nice copyediting this past week. What an effort!