info@lemonade.be +32 476 522 867 Follow us on LinkedIn Follow us on Instagram

Technical writing tips and tricks

Andrea Bonet
Written by Andrea Bonet
(Junior) Full Stack Developer at Lemonade

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.

Technical Writing Tips

1. Introduction

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:

    1. Introduction
    2. The curse of knowledge
    3. Simplicity and neutrality
    4. Effectiveness
    5. Style

Technical Writing Tips

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”)
Technical Writing Tips

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

Technical Writing Tips

4. Effectiveness

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.

Technical Writing Tips

5. Style

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”.

Sentences will generally sound strange if we start them with a piece of code or a mathematical expression; we can introduce them a bit later on the sentence.

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.

Maybe you are also interested in...

 
Software Development Case Studies

Docker - A quick guide through docker’s amazing world for devs

Software Development Case Studies

Function as a Service (FaaS) in action with Fission

Software Development Case Studies

ICS2: What is it and what does it do?

 

Your passionate advanced software development team