7 rules for creating world class technical documentation

No readers like this yet.
pink typewriter

Original photo by Marco Tedaldi. Modified by Rikki Endsley. CC BY-SA 2.0.

Bob ReselmanAt the 2016 Southern California Linux Expo (SCaLE 14x), long-time tech writer and editor Bob Reselman will give a talk called The 7 Rules for Creating World Class Technical Documentation, v.2016, which is based on an article he wrote more than six years ago. In this interview, he offers an update to the rules, and talks about how attitudes toward project documentation are changing.

If you were writing your article for the first time today, would you have the same 7 rules for creating world class technical documentation? Or have the rules evolved since then?

Well, here are the 7 Rules:

  1. Dry sucks.
  2. Before you start, be clear about what you want your reader to do after you end.
  3. Write to a well formed outline, always.
  4. Avoid ambiguous pronouns.
  5. clarity = illustrations + words
  6. When dealing with concepts... logical illustration and example.
  7. Embrace revision.

The rule that has evolved most for me is #1: dry sucks. When I wrote the rules initially, I was a big proponent of humor as a way to avoid dryness. I've evolved to think that engaging content makes the work not dry. Yes, some of us still like humor. But the more I do this, the more I find that clear, reiterative writing that uses attractive, accurate, understandable illustration takes away from a lot of the dryness in the technical documentation landscape.

What are the most common mistakes you see in open source project documentation?

That's a hard one for me to answer. There is a whole lot more good stuff going on than bad. I think that the importance and prominence of the Read.ME file, along with markdown has made consistent, useful technical documentation a way of life for the development community. Yeah, things go stale, which is usual for any documentation over time, but all and all things are on an upward trend in text-based documentation, anyway.

Which projects stand out as having exceptional documentation? And which ones would benefit from a documentation overhaul?

I can't really point out to any one project because there are so many. But in terms of commercial work, I think the folks at New Relic are getting it right. They have a well-constructed taxonomy and the content to back it up. The company produces short, useful videos that get right to the point.

Also Akka.Net is doing an impressive job. The text documentation is visually clear and organized well. Each page of documentation shows the outline organization on the left margin, so you can read through or pick and choose. They've obviously planned things out. They are very big on making it as easy as possible for people to use their technology.

Of course, in terms of being able to present massive amounts of documentation, you gotta admire the work that AWS does. They are still a little lacking in terms of visual display of the UI when it comes to their HowTos, but overall, they do manage to capture and present a huge taxonomy that is more useful than not.

Have you seen attitudes toward project documentation—and the people who write it—change over the years?

For big companies and tool providers, the documentation is always getting better. The economics of the situation demand that they do everything to keep their user base happy. However, for smaller to mid-size companies, particularly those that have an IT department rather than a software development unit, I am not seeing the sort of progress I hoped for. The notion that any company that produces software or systems should have a technical editor on staff is still hard to sell. Either the hope is that one day they will hire a sole technical writer to make it all better, or they think that the current documentation efforts of the software developers are good enough. While it is true that all content creation needs to be generated by the subject matter expert, a good technical editor can teach content creators how to be more effective. Also, the tech editor understands the big picture, the overall taxonomy of the knowledge base that needs to be satisfied, as well as the style guidelines required to make the work consistent in the short and long term.

And then there is the continuing emergence of video as a documentation resource. I am going to talk a lot about video in the 7 Rules 2016 talk. There is a lot of work to be done.

I have a vision: 2016 will be the Year of the Open Source Haiku. What's your documentation advice, given via haiku?

That which we value,
should be well documented,
delightfully so.

User profile image.
Rikki Endsley is the Developer Program managing editor at Red Hat, and a former community architect and editor for Opensource.com.


I love your rule #1 and "avoid ambiguous pronouns." Great interview.

In what universe does the documentation described here exist? I haven't seen useful information in a Readme file in many years. Readme is almost always restricted to license and author credits. If you're lucky, there's an Install file at the top of the source code, and if you're really lucky it's not just the generic Install created by GNU Autoconf, but actually mentions some details related to the product you're trying to compile.

I've run across good documentation here and there. Apache is well documented. The Debian manual was pretty good until systemd came along, and it will be pretty good again when it catches up to that change. The PostgreSQL manual is excellent. But those are the exceptions. Pity the poor fellow who has to set up CiviCRM without the benefit of years of tutoring on the disorganized pile of Drupal. Or the sucker who takes over a Ganglia installation and discovers its extensive third party volunteer documentation covers an obsolete version, and the rewrite remains undocumented. No, half hour videos with someone droning on while you try to follow their mouse and figure out what's going on is no substitute. "Hints and Tips" are no substitute for an organized, indexed manual. Forums where questions go unanswered, or wrong guesses at an answer that stand uncorrected, are no substitute.

The emperor wears no clothes on this one folks. Most open source documentation is not much better than useless for troubleshooting. I believe it's the #1 reason the Linux desktop never took off.

If you like Tech Haikus - I commend Philippe Nave's "Haiku Tech" to you. It's funny, and less than a dollar. I'm sure they don't want links here, but it's hilarious for techies.

Thanks, Alan! I found it on Amazon and will check it out.

Creative Commons LicenseThis work is licensed under a Creative Commons Attribution-Share Alike 4.0 International License.