Want to Write Better Technical Documents?

Overview

If you are in a technical field, chances are that you read and/or write many technical documents. You may have also read documents that felt, at least in parts, too dense, too confusing, too boring, or just plain irrelevant. Here I present one approach to writing better technical documents, so you don’t be that guy whose writing has these issues. Instead, (1) you write by first designing your doc hierarchically, (2) a large audience gets your idea at a high level, (3) a smaller but critical audience appreciates the details and then advances your work, and (4) profit! If this feels interesting, read on.

What is my credibility on this topic? Over several years working at Google, Facebook, and in grad school getting my PhD in a very technical field, I have written and read many, many documents, received many rounds of feedback, reviewed hundreds of conference and journal articles and whitepapers to decide on their acceptance for publications, and of course overheard friends and colleagues say the following at various occasions (actual quotes):

• “really well written”
• “good idea but very verbose”
• “not descriptive enough”
• “did not understand the core idea”
• “I dozed off, sorry”

and so on. By reading hundreds of technical documents and then hearing the popular verdict on them, I have developed a clearer understanding of what makes for effective tech document writing, and would love to share with you all.

In the tech industry we often call technical documents design documents. This article is about designing your documents better such that the design story you are telling has even wider reach and achieves even greater impact.

The Basic Premise

An observation that drives the core idea is this: The audience for any technical article starts to drop off after grasping the initial bit (or failing at it), then skimming through content, peaking at interesting stops (cool diagrams, eye-catching comments, intriguing data, etc.), and a final peak at the conclusion. This is not scientific, but based on lots of anecdotal evidence. Readership of technical documents might actually vary like this:

The green line in Figure 1 is the holy grail for us writers, but unfortunately for technical documents, the red line is more representative. By contrast, in well-written narrative pieces (e.g. fiction), the audience would typically read sequentially in order to stay in sync with the story the way it is told (and thus more like the green line in reality). Well-written stories are engaging-enough that reading sequentially and completely is the core of their entertainment value. Therefore the idea here applies primarily to technical documents. Rather than making the green line our goal, we could embrace the reality of the red line, and tailor our writing to maximize impact.

The Technique

So here goes: Write your document structure hierarchically, starting with the most fundamental concept, idea, finding, etc. and then progressively unraveling the details. You can do this with a 3-step process:

Step 1: Create a Hierarchical Tree Structure.

First, write the high-level structure of your doc in the form of a hierarchical tree structure of concepts, ideas, details etc. The hierarchy should be such that your core idea (root) reaches all of your target audience, and lower down, progressively fewer and more specific subsets would care enough to read. Visually, it would look something like this mock:

If we drew a Venn Diagram of your ‘interested audience’ at each node, it might look something like this.

Note how the core idea has an audience many times larger than the audience that would care to read all the details. The positive way to look at this is:

• You have a large audience for your core idea, if it is of general interest. This is an important accomplishment, so aim for this in your structure.
• You have a small but critical audience that would care about all the details, e.g. close collaborators, those who will advance it, bring it to life, etc.

Step 2: Flatten the Tree Structure.

Once the hierarchical tree structure of concepts, ideas, and details is written out, create a flattened structure of sections. There are three things to consider:

• Your readership would peak at the beginning and at the end (Figure 1).
• Your core idea needs to reach the most number of readers (Figure 3).
• Your audience will drop off progressively.

Considering these together, you can create a flat structure as follows:

• Beginning and Ending: You want your beginning and ending to cover the core idea clearly and concisely, even if redundantly in both places.
• The Middle: The rest of the details of your technical document goes here. Your want to organize these details into logical sections.
• The Sections: Choose an ordering of the detailed sections that (a) feels like a good logical flow of your work, and (b) more interesting sections are higher up assuming your audience progressively shrinks. An exception is that if sections have dependencies among them, e.g. you can’t talk about idea 5 before introducing idea 4, then you have to maintain that partial order. Otherwise the document will become incomprehensible in parts.
• The Recursion: The final trick is recursion, i.e. apply these same principles to each section and subsection, i.e. top-load each section with the core idea of that section, and keep the more interesting ideas higher up.

In the above example, following the above guidelines, we took the tree structure from Figure 2 (a hypothetical example) and proposed a flat structure for actually writing out the doc. Some salient points to be noted:

• The core idea is repeated in introduction and conclusion.
• The three detail blocks map to three sections, but order has changed.
• The order of importance is determined to be Details 2 > 1 > 3.
• Within Detail 2 , we started with the core idea of detail 2, and then More detail 2.1 > 2.2.

Step 3: Write out the details.

Finally, once you are satisfied with the flattened structure, go ahead and write out all the sections and subsections. Do proof-read to make sure that this somewhat mechanical approach to designing your document doesn’t take away from the overall readability and flow of your content. Pay particular attention to transitions, e.g. whenever possible, at the end of each section, lead your audience to the next section so that they remain engaged and motivated to continue reading.

Bonus tip: Retention in this context is the rate at which you can keep as many of your readers reading without skipping sections or dropping off entirely. If at all possible (and most often it is not), write your technical document like a beautiful story. Then your audience will keep following along and you will have high retention rates. The graph in Figure 1 for your doc would look more like the green line than the red line.

Let’s move from the toy example above to a more realistic one.

A Realistic Example

In order to drive home the points made so far, let’s work on a more realistic example. In the spirit of recursion and eating your own dogfood, let’s try this out on this article itself. Though this is not a very technical document, it has some of the same ingredients.

So, what are my key ingredients?

• Core Idea: We can write better technical documents by first designing the document structure hierarchically, like a tree.
• Detail 1: How exactly to design the document? What’s the technique?
• Detail 2: What’s the basic premise behind why this idea will work?
• Detail 3: Can we get a real example of this?
• Detail 4: What is my credibility that you would value my advice?
• Conclusion: Repeating the core idea, and then some.

Within Detail 1, i.e. the technique, there are three more detailed ingredients:

• Step 1: Creating a hierarchical tree structure.
• Step 2: Flattening the structure.
• Step 3: Writing out the details.

If we did the exercise above to create the tree structure first, and then form the flattened sectional structure, it would look something like this:

A couple of notes about the flattening of the above tree structure:

• I ended up reordering the details as follows: My credibility > Basic Premise > Technique > Real example. For example, if ‘examples’ came before the ‘technique’, it would be very hard to follow the example.
• The subsections on techniques were not reordered because they are a sequence of steps that must presented in that order. So there’s a dependency among the blocks, so an exception applies.

Conclusion

Thanks for coming this far. I know that it’s highly likely that you jumped to the conclusion. If that’s the case, thank you for validating Figure 1 above.

To quickly recap, in this article I presented an approach to writing better technical documents by first designing their structure hierarchically keeping in mind the reality of Figure 1, flattening them into meaningfully ordered sections and subsections, and only then filling in all the details. This way, most of your audience would get your core idea/insight/concept, a large subset of them would get your most important details, and a good flow (like a good story) would ensure your article has good retention.