Notes on Technical Writing

A few suggestions on what to do and not to do

This one is a little bit different. It is not about DSLs, but about writing. I have been writing a lot over the last couple of years — blog posts, papers, and books — and I was also involved in helping younger engineers to get a grasp of how to write well. And maybe even enjoy it a bit.

This post is a collection of best practices that I try to stick to when writing. They might not be totally obvious for people who do it less. Needless to say, all of them only apply to non-fiction writing, and in particular, text that explains (or argue for) technical topics.

Before we get into the specifics, there are two preconditions you should think of. First, you must have something relevant to say. In other words, you have to define a target audience that is interested, because that is more or less the definition of “relevant”. Once you know your target audience, you should figure out what they already know so you don’t bore them with too much repetition. And you should understand the aspects they are most interested in and the level of detail they will be willing to follow you to.

The second thing you should think about before starting to write is: do I actually know what I’m talking about? Do I have enough understanding of a topic so that I can explain it well to my target audience? Even if your goal is to explain something in a simple/superficial way, you will probably have to understand it much further to be able to judge what is relevant and what is not.

Alright, so let’s dive into the details.

A good Abstract

In many technical writings the abstract almost sounds like an introduction, and/or the introduction repeats the abstract. This is annoying, nobody wants to read the same thing several times (there are exceptions, see below). In particular, the abstract should also briefly mention the solution and/or results of your writing, its purpose is not to build suspense (“you’ll learn about my clever idea if you read 10 more pages”).

The purpose of an abstract is to help the reader decide whether to invest the time to read the rest. You should give them as much relevant info to make this decision as possible.

Similarly, the conclusion or summary part of the paper should not just repeat, yet again, what you’ve already said (“In this paper, we have explained …”). Instead, bring in some vision or future outlook.

Overall Structure

The recommended overall structure of your document obviously depends very much on what it is you want to communicate and it is hard to give definitive guidance. The three-part introduction/main/conclusion structure we’ve all learned in school isn’t wrong, but it is probably a little bit too simple for most technical topics. I find the format used by software patterns very useful; while there are differences in the details, most pattern authors stick to the following outline:

· Context — where are we coming from, where does the problem occur

· Problem — what are we trying to solve with whatever we describe in the text

· Forces — which influences guide the way we are going to solve the problem

· Solution — how, in general, are we approaching the problem and what is the general structure of the solution

· Implementation — what are relevant details of the solution, things that have to be kept in mind or addressed specifically

· Tradeoffs — what are the good and bad aspects of that solution, ideally connecting to those the and potential alternative solutions

· Resulting Context — where does this leave us, what do we do next

This idea of starting with context, problem and rough solution is really crucial. I can’t think of many writing where this is no the right choice.

Importantly, you should sprinkle interesting and illustrating examples throughout the sections. For most people, examples are what helps them understand.

There is one more thing. Even though a non-fiction document should not have an arc of suspense, you have to tell a story. What I don’t mean by that is what you find in science communication quite often these days, where a text on a particular technical topic is built around the personal story of a scientist. In fact, I hate that. But a document written as a tutorial that takes the reader along as we solve the problem is often much more readable than a “reference documentation” which lists facts and their relationships. One particular step to help with this is to try to write in the “we” style, where “we” refers to you, the author, as well as the reader. You’re going on a “journey” together.

What’s in a paragraph

Alright, let’s get a little bit more concrete. Paragraphs. A paragraph should contain one idea. To force yourself to stay with that one idea, it is very useful to give each paragraph a one/two/three-word title (at least during the writing process, you might delete it for the final release). A paragraph should also be more than a single sentence. An example of how not to do it are the texts found on many US news websites, where a paragraph is often only one or two sentences, and all kinds of unrelated things are mentioned: “The plane, operated by Los Angeles, Calif. based company Flycorp, crashed and burned during landing after taking off in San Francisco”.

Consistent Abstraction Level

Make sure you stay on the same abstraction level within each part of the text — it applies to paragraphs just as much as for sections and subsections. This is the reason, why in the pattern format above the solution is separated from the implementation, you provide the details later after you have sketched the overall landscape. Importantly, when you describe the details, you should continuously point to how they fit into the big picture.

This is useful for two reasons: first, often it is helpful to understand the complete big picture to be able to understand details. And second, people who do not need the details can only read the part that describes the big picture and skip the rest. A particular example are computer science papers that sprinkle the formal mathematical stuff all over the paper instead of first explaining the idea and then having one section where it is formalized.

Make reasoning explicit

This one is hard, but it is central: make sure you make your reasoning transparent. Explain the intermediate steps. Consider this example: “The aircraft had a problem right after take-off, so it had to circle for two hours before landing.” It’s probably not clear to you why the “problem after take-off” causes it to circle for two hours. Let’s rephrase with the reasoning included: “The aircraft had a problem right after take-off. Since it was scheduled to fly to Japan, it had a full load of fuel and therefore was significantly heavier than its maximum allowed landing weight. Landing this heavy would risk damaging the airplane. So they circled for two hours to burn and dump the fuel and become light enough for a safe landing.” Whether and how much of this additional explanation is needed depends on who you explain it to, but even for aviation nerds I would say “… so it had to circle for two hours before landing (max landing weight!)”.

A related topic is to use the right connectors. Some words (because, since, so) suggest causality, whereas others (and, but) suggest a (temporal) correlation. “The guy didn’t wear a helmet while biking {so|and} was hurt when he fell.” Depending on whether you use “so” or “and” in this sentence, you express something quite different. It is astonishing how often I have seen text get this wrong, suggesting causality where there is none or reducing causation to correlation.

Make assumptions explicit

This one is related to the previous. Make assumptions about what you expect the reader knows explicit. “The beam diverges as it travels along the beampipe, which is why it has to be focused actively”. The author assumes that the reader knows that * the beam is made of protons * protons are all negatively charged * they are initially close enough so that they feel each other * so they repulse each other * and make the beam get “wider”. Just as in the reasoning example, tell the reader what you expect them to know and maybe point them to additional reading. You could write this as: “Since the beam consists of tightly packed positively charged protons, they repel each other (see [ref] for details) and the beam diverges as it travels along the beampipe. This is why it has to be focused actively.”

Point out Navigation

Many topics are quite expansive and faceted. Likely, you will touch many aspects of the topic as you write about it. Make sure that you explicitly say when you’re moving to a different aspect. Here’s an analogy: Imagine you’re describing the interior of a house. Your readers probably can’t make much sense of your descriptions if you don’t say when you start describing a different room.

Avoid unnecessary synonyms

Within a particular community there are often many terms for the same idea, maybe subtly different in detail but potentially exchangeable in many circumstances, or just slang terms. Your readers might not be aware of the fact that these different terms are synonyms, which might make a text very confusing to read. A particularly nice example is that some people in the gliding community called their aircraft a “ship”. Imagine you’re reading about aviation and then people start talking about ships. Very confusing. So avoid the needless use of synonyms, especially relating to technical terms in a particular domain. It’s also generally a good idea to define terms and the relations between them. So if you need to use a (almost) synonym, explain what the difference is and why it is important.

Justify Claims

Whenever you make a claim, make sure you justify it. In a science paper, such a justification must be a reference to other published work or a cross-reference to a section of the paper where you provide a justification (see a collection of common proof techniques here). Oh, and don’t use a reference as the subject of a sentence (as in “[12] argues that …”).

In non-scientific writing, the requirements are less strict, but you should at least provide a bunch of examples, a short “because” clause, or a pointer to an assumption you make. Just a naked claim is annoying to the reader.

Stylistic Variation

There are many more stylistic options beyond just chaining sentences together. For one, there are colons, semicolons, and dashes. You can use all of them to vary the way you structure your sentences. But aren’t there other stylistic means as well? Yes. There are rhetorical questions, (potentially made-up) verbatim speech, quotes from famous people, and analogies. “Overusing those might make a text look gimmicky but judicious use makes the text more interesting”, a copyeditor once told me. Enumerations and bullet points are also an option, but they are traditionally overused in an attempt to make things concise. This is annoying because

· they tend to skip the connectors between the items, which is where much of the interesting story often hides

· they waste space in papers where the page count is limited

· they make the layout look ugly

The first of these, plus the “story” thing I mentioned earlier is also why I generally prefer to writing a document over creating a Powerpoint: the latter leads to you bulletpoints that don’t flow and don’t connect.

Shorter Sentences

A lot of apparent complexity, especially in science papers, comes from sentences that are way too long and complicated, so it is almost always better to use multiple shorter sentences cleverly connected instead of one very long one, but don’t overdo it though, because it might read simplistic or childish. Also, you’ll get half of the commas wrong.

Avoid gratuitous color

It really is very important to avoid these annoying filler words like “really”, “very” or “annoying”. While it is sometimes a deliberate stylistic choice to add them, most people sprinkle these words all over the text without thinking much about them. Don’t.

Edit!

Never publish a text directly after you’ve written it. Leave it alone for a few days, come back to it, and improve it. This is a good time to explicitly look for some of the things I’m suggesting in this text. You should also try to get at least two other people, ideally from your target audience, to read the text and give you feedback on content, logical structure, and style. And if you do not write in your native language (or unless you are very experienced) it’s probably a good idea to have the text proofread by a native speaker. I don’t know how many science papers I had to review over the years where I was turned off just because of really bad language. This is unnecessary. There are also tools such as spellcheckers (which you have to use) and grammar checkers and style optimizers (which you should consider using).

Summary

Obviously, this is not a complete guide for good writing. That would be much longer, and I am certainly not the right person to write such a guide. For that, I suggest you read Steven Pinker’s The Sense of Style and/or Williams’ STYLE, The Basics of Clarity and Grace.

Acknowledgements

I have made a few changes to the initial version of this article after some suggestions by Johannes Link and Tamas Szabo. Thanks guys :-)