Skip to content

Instantly share code, notes, and snippets.

What would you like to do?
A Very Short Guide to Writing Guides

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.


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 teenagers, so I shy away from images of pop icons and memes. I use jargon and words like "identify" rather than "peep this".


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.


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.

Copy link

rk101288 commented Nov 10, 2017

Excellent write-up, Eric. I like that you emphasized on identifying the audience and explaining the purpose of the blog. You asked for suggestions above, so I am taking you up on it. Would you consider changing:

My audience is technical people who need to communicate technical information, and not teen girls ...


My audience is technical people who need to communicate technical information, and not teenagers ...

Our industry is already famous for stereotyping girls. While I understand your intention, your sentence about teen girls can easily be read as that girls, in general, cannot be technical.

I would love to hear your thoughts.


Copy link

coderoshi commented Oct 14, 2020

Thanks @rk101288! Excellent points, and I wish I would have seen this comment 3 years ago

Copy link

rk101288 commented Oct 20, 2020

No worries @coderoshi thank you for considering it!

Copy link

IvoryHoward commented Mar 21, 2022

I've never been very gifted as a writer. Whenever I was required to write a research paper for school, it was almost always a source of great annoyance for me. Keeping this in mind, I saw that my grades started to decline, and I resolved that this would not continue. I chose to seek for a reputable writing service and eventually settled on college paper assistance as the most suitable option. This organization assisted me with writing in the least amount of time feasible and at a reasonable charge.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment