Technical writing tips and tricks
Have you ever wanted or needed to write a technical text and didn’t know where to start? Have you ever read a technical text and felt lost by the second paragraph?
Don’t worry, we all have!
A technical text must deliver technical information to readers in an understandable and organized manner. In this article we will go over some tips and tricks that can help you achieve that goal!
These techniques are based on Google’s technical writing courses content + personal experience, so you can also check Google’s courses for further information.
Although there are several things that can be included in a document’s introduction, we can always start with the three basics: what, who, and how.
● What is this document for? What scope of content does it contain?
- For example:
The purpose of this article is to give some general tips and tricks for technical writing.
● Who is the target audience for this document? Is it for experienced programmers, new developers, engineers…?
- For example:
The intended audience for this article is: software developers, data analysts, project managers, and any other technical workers that want to know more about this topic, as the concepts are very beginner friendly.
● How is this document structured? How many sections, how many subsections, etc.
- For example: This document has the following sections:
2. The curse of knowledge
3. Simplicity and neutrality
2. The curse of knowledge
Expert understanding can ruin explanations for newcomers. Sometimes we assume that the reader has all the necessary background to understand us, but they might not!
● That is known as the curse of knowledge, and can manifest in many ways:
- Using advanced concepts, assuming that the reader is familiar with them
- Writing for a beginner audience and skipping basic steps or concepts
- Not giving sources or references for very specific/specialized information
- Quantifying (for example: “This is very simple”)
3. Simplicity and Neutrality
A significant percentage of technical readers are more comfortable in languages other than English.
● Keep your writing culturally neutral (idioms!)
● Prefer simple words over complex words
● Don’t omit the subject in a sentence if it can be ambiguous
We can use these resources to make our texts faster and more optimal to read.
● Shorten sentences: A short sentence will always be easier to understand than a long sentence, with lots of different parts. As Kevin Malone from the show The Office once said: “Why use many word, when few word do trick?”
● Use lists: We can use lists instead of enumerations in long sentences. They are faster to read and easier to remember.
● One paragraph = one topic: As with sentences, the shorter the better! Too many ideas in just one paragraph might make it too long and complicated to understand.
● Key points first: The reader will understand our points better if they know what we are talking about when they start a sentence.
● What, why, how: We can use this trick to organize paragraphs. A little sentence talking about what the paragraph is about. Next, we can talk about why the reader should find this useful. Lastly, how the reader can use the information we just provided.
Style is not only used for aesthetic purposes, but it also helps readers form an image in their minds.
● Active vs Passive: Active voice is generally shorter and clearer. Most readers will “reorder” passive sentences in their minds while reading, to form an active sentence. There’s no need to give them this extra work! The passive form can also focus too much on the subject, when we want all of it to be important.
An example of a (passive) sentence:
- The moth was removed by Grace Hopper.
And the better version (active):
- Grace Hopper removed the moth.
● Take extra care with names! For example, the document editing software, LaTeX, should be spelled like that, and not plainly “latex”.
There is so much more to learn about technical writing that we can’t fit on this article, but as a last tip: re-read everything!
That’s the best way to keep improving, and that’s exactly what I’m going to do after finishing this sentence.