public
Last active

A Very Short Guide to Writing Guides

  • Download Gist
gistfile1.md
Markdown

A Very Short Guide to Writing Guides

This is just a few thoughts on the topic of writing technical guides. This was intended for Basho's engineering team, but this may apply to open source projects in general.

Audience

It's commonly preached that the first step in writing is to identify your audience; to whom are you writing? This is the most well known, most repeated, and most overlooked step of writing in general and technical writing in particular. Take this document, for example. My audience is technical people who need to communicate technical information, and not teen girls, so I shy away from images of pop icons riding unicorns. I use jargon and words like "identify" rather than "peep this".

Pronouns

The flipside of the audience, is you. Although you should get out of the way of the material as much as possible, our language doesn't exactly account for that without sounding like a 50's robot (use active voice; we don't have to pretend like we are not real humans). Use collective pronouns like we or us. Don't use I unless you're writing a blog post. I'm using I because I'm talking to you, as me, Eric Redmond; however, our technical guides should be written as Basho or as the Riak Community to someone in particular.

Guide or Reference

With the audience clearly marked, the next step is knowing and identifying what kind of document you want. This is easy and important, as long as you know what you're trying to convey.

  • Reference: A Reference is just a technical list or table of raw information. It should be complete. Never write a partial reference, because it's pointless. If you have a reference of HTTP commands, delineate every command, because missing one or two is maddening, and users have every right to be pissed when they later learn the setting they've searched for for hours is undocumented.

  • Guide: Writing is not about the words. That's why we call these documents "guides," because they, well, guide a user through some thought process. This is much more art than a reference is, but there are some useful rules we can follow.

One thing to note is that a guide is not a replacement for a reference. To paraphrase Mike Pope: If there is no reference, it doesn't exist. Don't ever "mix and match", trying to combine a lookup reference within a guide. There are many reasons, but the basic ones are: 1) the reference will never be complete without making the guide overly long, and 2) it's not nice to make your audience read lots of prose just to look up some simple fact, like how to configure a PB port.

Answering Questions

Technical writing should teach someone how to do something. The easiest path to this is to be clear. A good start is by answering a couple implicit questions your reader will have.

  • Why should I care?
  • What new thing will I be able to do?

(If these questions look familiar, I long ago synthesized them from Dave Thomas and Andy Hunt... so, credit goes there)

I can't stress the importance of answering the first question. If you can't explain in the first couple sentences of the guide, why should the reader bother reading? Respect their time, and give them motivation for reading on. It's like a built-in TL;DR. For example,

In this guide we'll learn how to increase write performance.

The second question is equally important. You don't need to state upfront what the reader will be able to do. But if they read your document, and are unable to answer this question, what was the point?

I tend to try crafting the two question answers into a single statement early on, as a courtesy to the reader.

You can predictably increase write performance by adding more nodes to the cluster.

This is, IMHO, a big step that seperates good from mediocre tech writing. It puts the reader in the correct frame of mind for the following. This isn't a single sentence that each document must answer, but instead, a question that every section must answer on its own. If a section cannot answer these questions, consider removing it.

Navigation

This is a bonus step, something to keep in the back of your mind. Though not part of the document writing process per se, this can help keep our constellation of docs in a cohesive shape, suitable for navigation. Where will this document live, in the grand scheme of things? A blog roll? A wiki? Public docs? Private docs? What keywords can be associated with this document? What's a great title (I actually like to create titles last, but that's just a preference)?

That's all for now. This might be considered a work in progress, but I didn't want to be too hardnosed about it. Suggestions welcome.

Please sign in to comment on this gist.

Something went wrong with that request. Please try again.