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.
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.
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.
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:
to
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.
Thanks!