Update: Simon Peyton-Jones has basically made every point I’d like to make, and done so more entertainingly.. Check it out!
I’ve recently had the opportunity to mentor a student during his graduation project. He was a great coder, but had a lot of trouble writing up his report in a good, formal style.
I wrote down a list of writing tips for him, and I thought I might as well put them on-line so I can point other people at this page in the future.
These tips mostly apply to technical writing, as they are intended to make the text more easily digestible and scannable. Efficient transfer of knowledge from the text into the head of your reader is the goal here, not storytelling. They are in no particular order.
- Use the active voice (the passive voice shall be avoided)
- Start a section with an introductory sentence that explains what the section is about and its relevance. Why should I care about this section?
- Use “we” instead of “I”.
- If you have a list or summation: start with a list of bullets, then have a paragraph or section adding detail to each bullet point if necessary.
-
WHY is more important than WHAT is more important than HOW.
a. Unless HOW is really tricky (but then WHY is it tricky?)
-
Be concrete.
a. Give examples where possible.
b. Don’t use a generic term if you could use a more specific one.
- If you have figures in your document, number them and refer to them by number: “figure 3 shows a diagram of …” or “as shown in figure 8”.
- When writing about a design decision: introduce the problem before describing the solution.
1. Use the active voice
Don’t write “An application has been written”. Instead, write “I’ve written an application” or “We’ve written an application”. Technical documents are written for clarity, and sentences with the active voice are simpler and easier to understand.
2. Start a section with an introductory sentence
Assume your readers (a) don’t know anything about your subject matter and (b) don’t have a particularly good reason to want to learn about it. Both assumptions will usually be very close to the truth.
As a writer, we’ll have to make the reader want to read the section, by piquing his interest. Additionally, introductory sentences help make the document more skimmable: if the document is structured properly, the reader should be able to determine after reading the first sentence of a section whether it is appropriate for him or if he could skip it.
3. Use “we” instead of “I”
If you’re going to be using the active voice (and you should!), you would end up using the word “I” a lot. If your reader reads “I, I, I” all the time, he’ll think you’re a very conceited person. Instead, take the reader on a journey and make him feel like part of the work (alternatively, pretend there were a lot more people doing the work than there actually were).
Ultimately: people trigger on certain words, and in natural language, “I” is only used to draw attention to the identity of the writer. This is great for a resume and a press release, but in technical documentation, the content and the actions matter more than who did them.
4. First give an overview in a list, then elaborate
Again, this enhances the skimmability of your document. First give an overview, then drill down into the details. Your reader will more easily be able to build up a mental model of your content if concepts are introduced in this way.
5. WHY is more important than WHAT is more important than HOW
When you need to save time (both your time writing, as well as the attention span of the reader) or space (pages, mental capacity of the reader), be sure to write about topics in the order above.
Similarly as to how a newspaper article is written in such a way that you can stop reading at any point as far as your time allows, and still get the most important points across (later paragraphs are for adding more detail), you should write about the most important things first. You may even omit the later parts. Given a WHY, a reader should be able to infer a WHAT. Given a WHAT, he will be able to infer a HOW (unless it is very non-obvious, of course).
6. Be concrete. Give examples. Don’t use vague language.
Also in this category: “don’t use weasel words”. Be as concrete as possible. If you need to be general because you are introducing very broad concepts, give a couple of examples to give the reader an indication of what you’re talking about.
Most people are better at looking at examples and inferring the generality (in fact, our brain is a machine that is specifically tailored to do just this!), than inferring all implications from a general rule.
7. Number your figures and refer to them
Don’t make the reader guess what figure you are referring to in your text, and don’t make them guess at the purpose of figures. Also, caption your figures.
8. Introduce the problem before describing the solution
Don’t write: “The buffer is 9MB. This is because the largest photo we need to process is 1500x2000 pixels (at 24bpp)”. Instead, describe the problem before the solution: “The largest photo we’ll need to process is 1500x2000 pixels. At 24bpp, the size of this photo is 9MB. We’ll therefore use a buffer of that size.” Structuring the text in this ways makes it easier for the reader to follow your train of thought.
This is the list so far. I’ll add to it when I think of more.