It’s surprising how often I’ve been asked this question over the last few months. Once upon a time — some dozen years ago — I was a technical writer. I wrote manuals, technical documentation, and various forms of other literature for a living. And, to be quite honest, I hated it.
Well,hate is a strong word. I got bored of doing it. (Long story, suffice to say, I ended up making websites for a living.) But certainly the skill has never left me (I still write documentation to this day as part of my job), and I do know a few things about writing clearly and effectively.
Sadly, it’s not something that is done particularly well…
If you’re reading this, you’re (obviously) on the internet. And you’ve seen how badly the internet has been written. Spelling mistakes aside (even today’s modern spell checkers miss grammar and some syntax resulting from correctly-spelled, but incorrectly-used words), many people have trouble forming a cohesive idea, and an even harder time expressing it. As much as some scholars have said that the internet has (overall) improved the habit of written communication, I personally find the quality a bit lacking at times.
These days, you can easily find some fantastic how-to books on how to write documentation. This is not a new field, by any means — humanity’s been writing stuff like this for a couple hundred years, really. But over the years, I’ve found that most of the details can be boiled down to a few key points that you always keep in mind, and then you need to practice them over and over and over and over and over and over.
Oh, and you need to have a vicious editor. (Ideally, another writer with more experience.) Someone who can objectively tear apart your work, show you what’s good, what’s not so good, and help you improve your work. I learned more about the art of technical writing from two editors than I did from any book or professor, and I’m thankful for those people’s efforts (regardless of any heated arguments at the time). Writing is a two-person job: the author and the editor, and I’ll debate anyone who says otherwise…
There’s six fundamental parts to any good documentation (technical, or otherwise):
- Organisation of concepts
- Understanding your audience
- Clarity
- Brevity
- Visual reinforcement
- Consistency
Organisation
This is Number 1 on the list for a reason. Even if you bugger everything else up in your documentation, you need to get this right. How you divide your document really speaks to how you introduce the concepts, explain them, and allow people to dig into things at a pace that’s comfortable for them.
As a general rule, you always start at a very high level — you introduce the very thing you’re about to explain. For example, imagine you’re writing a document on a plane. Your document may eventually detail the specific bolt that’s used to attach the engine, but you first have to start by telling the reader what a plane is, what it does, and (in some cases) even a wee bit of history. (Incidentally, a lot of Wikipedia articles are organised like this, and many are good examples of documentation.)
You then break your document into sections (or chapters, whatever you want to call them), which are the major topics of discussion. In the case of a plane (for example), you might want to have sections for the fuselage (the basic chassis of a plane), the powerplant (what makes a plane move), the wings (what makes a plane actually fly), the avionics (what helps the pilots steer the plane), the landing gear (because everything that goes up eventually has to come down), and the empennage (basically, the rear control mechanisms at the tail that allow steering).
Then, within each of those sections, you can more succinctly break down the topic more independently, allowing each section to have isolation from the other sections. Though not total isolation — any good documentation should refer to other parts of itself, or other documents, that provide additional detail.
It’s a simple mantra: start big, go small.
Thus we get to headings! All documentation has headings — it’s what breaks it up into parts that are digestible. All documentation has a heading hierarchy, too: always going from the first heading (often called Heading 1) to the second, to the third, and so on. You never, never, ever skip a heading. If you feel the urge to skip a heading, you have a flaw in your organisation.
The depth of heading hierarchies (how many heading levels you need) depends on the document. Some documents can get away with two; some (and I’ve written ones like this) need six or more. Don’t creating heading levels you don’t need — always keep a document as shallow as you can — but don’t be afraid to use them when you’re discussing a complex thing that needs a lot of breakdown.
It should be noted, especially with software documentation, that a heading hierarchy isn’t always a heading (such as “Organisation”, above). Sometimes it’s a function or a method that you need to document. For people reading API (application programming interface) specifications, the name of the function is in many cases far more valuable than heading you could create.
Understanding your Audience
It might sound trite, but you’re not writing a document for yourself. You’re writing it for someone else. You should always keep this in mind, as it will help focus the language you use, and the detail you need to provide.
Again, consider the plane documentation. There’s several different audiences who may need such a document: the people building the plane (they’ll need detailed specifications, including assembly instructions), the mechanics who’ll fix the plane later (similar to the build specifications, but they’ll also need information on best practices for repairs), pilots (who need to know how to fly the plane), and even passengers (they want to know more about the plane, and especially safety procedures). All of these audiences need special attention, and (frequently) very different information.
You would (almost) never write a general document that would address all people. It’s not to say that it can’t be done — it’s done every day, and done badly — but such a document becomes very hard to read, and even harder to understand. Writing different documents often helps make sure you’ve got the right subject and language for the right people.
Clarity
This is a tough one, and it relates to the previous two items. The more complex your topic, the more clarity you may need to provide. By “clarity”, I mean the ability to explain an inherently complex thing in (reasonably) simple terms.
I’ve written loads of technical documentation regarding software development and server architecture, often for project managers and clients who do not possess my level of understanding. (This is usually because I have to get budgets approved, and simply saying “we need to rewrite some code” isn’t good enough.) I’ve had to explain a problem in detail, propose the solution, and draw potential conclusions from the actions. All of it in such a way that someone who doesn’t need (or want) to understand the details.
I won’t lie: this is hard.
So how do you do it? Metaphor and simile. (I provided links, in case you can’t remember what those terms are. And yes, you could use allegory as well, but it takes a lot more effort, and we’re trying to keep things simple.) You need to convert the concept into something more familiar to the audience at hand.
For example, in software, we often talk about using a “framework” when building complex things. A framework is like being given a lumbermill to carve up an entire tree, rather than having to use a handsaw to do it all by yourself.
See what I did there? You’ve probably never sawed an entire tree by yourself — but you can imagine how much work it is. You don’t have to know what a “framework” really does, but you suddenly have an idea of what it can do for programmers. Hence, the importance of explaining things a different (but still valid!) way.
It’s important that you’ve explained a concept sufficiently. You have to carry an explanation all the way to the end, so that someone has a complete thought. Imagine if I’d stopped halfway through my framework definition, and left it at “lumbermill”. You’d probably be wondering where I was going with the idea, and likely no better off than when I’d started.
You also need to be specific. Avoid using vague words when you can use the actual term instead. This is particularly important as your detail increases. At a high level, you can talk about the bolts that go into assembling a plane; when you get to the exact bolt needed to attach a winglet to the wingtip, you’d better have the part number to go along with it.
Brevity
Those of you who know me will be snickering at me for this one. Yes, you need to try write the shortest documentation you can, all the while building on the items I’ve already mentioned. I say this because, generally, I still struggle with it.
It is very difficult to not want to explain everything in huge amounts of detail. I’ll tell you this (because I’m always telling it to myself): give people just enough information, not all the information — let someone learn enough to know what they need to get going, and they’ll (usually) figure out the rest for themselves.
Also, you keep it short because people just don’t want to read lots of words. They want the information, and move on. We’re a society of soundbites, not one of novels. That also means writing short sentences and short paragraphs — long ones are fine for telling stories, but they suck at instruction.
Visual Reinforcement
When you’re writing some documentation, you’ll come across the need to explain something that is inherently so complex that it’s difficult to write in words.
So don’t.
The saying “a picture’s worth a thousand words” is very true, and a single picture can eliminate the need to write lengthy explanations. In some cases, a diagram is the only way to properly provide information (such as technical specifications for the previously-mentioned airplane mechanics).
Do you have to make these diagrams yourself? Not always, but often a simple drawing tool will save you hours of hunting through the internet for an appropriate picture, or waiting for someone else to make it for you. Visio and Omnigraffle are life-savers when it comes to building quick and easy diagrams, especially where complex ideas like process flows need to be explained.
Consistency
I have this as a “last” important point, but it’s no less important than the previous two (Brevity and Visual Reinforcement). It’s important not because it helps convey information any more easily — it’s because it won’t annoy your reader.
Consistency, in this case, is about your writing style. You need to make sure you’re always approaching your writing in the same manner, in the same style, in the same voice, throughout an entire document. (This is where an editor really comes in to save a day, incidentally.)
Changing styles, or how you write, does not change the information you’re providing. But it does cause the reader to unconsciously start to hate you, because it’s difficult for a human to read different styles or word usage from page to page (or section to section).
Stick with your choice of spelling. You’ve probably noticed that I use “organisation”, not “organization”. I use a version of Canadian spelling. (This is in itself a bit debatable, as some Canadian spelling is British, and some is more American.) But once you start using it, keep using it. (Incidentally, I don’t normally use “organisation” — I’m using here to illustrate the point.)
You should also stick with your choice of terms. Once you start using a term, you need to keep using it, and use it in the correct context. As mentioned with the bolts earlier, if you ever mention a “19 mm close tolerance bolt”, you need to keep using that term, lest someone get confused with a different kind of bolt.
Similarly, once you start using a particular meme for your metaphors, you need to stick with them. If you start using planes as your metaphor, keep talking about planes — don’t switch to using trees and lumbermills. (See what I did there?)
Yes, this is a bit of psychology. But you want someone to read your document, and hopefully recommend it to someone else.
Some Final Notes
It ain’t easy summarising an entire career into a single blog post. Heck, it’s fool-hardy, really. But still, there’s a few other things that you might want to consider looking into.
First of all, read some examples. You don’t need to learn the material, but look at them for what they are. I’ve already mentioned Wikipedia, which is maintained by an army of editors, for whom I have the deepest respect. Also consider reading some books — things like the For Dummies series and pretty much anything out of O’Reilly are great examples of complex ideas broken down into digestible terms.
Your style is important, but not critical. Still, there are a few things you should keep an eye on:
- There is no “I” in technical writing, so don’t use it (the author might have a fancy picture on the cover, but inside the book they shouldn’t make themselves known)
- There is a “you” — always speak to your reader, it helps them attach themselves more to the topic
- Companies (et al) are referred to in the third person; avoid “we” if you can
- Avoid colloquialisms, vulgarity, stereotypes, catchphrases, and so on — those are for literature, not documentation
Learn some of the typographical aspects of writing. For example, the difference between a dash, an “en dash” and an “em dash”. You’d be surprised how often a simple change like that can affect the readability of a document. Similarly, spacing between headings and paragraphs, how to create legible lists, and simple formatting go a long way to making a document “friendly”.
Practice. You won’t get it right the first time. Or the second. Or the tenth. But you will get better, if you keep at it, and have a (trusted) person review your work.
