Technical documentation writing quick tips
Below you’ll find an assortment of quick tips to help you make your technical documentation (docstrings, READMEs) easier to read.
These are tips that I give colleagues and pupils based on practical experience. Writing is a skill, and people have written entire books about the subject; hence this is a “quick tips” article.
Important: This is a living document.
These tips should do well for any medium, but I keep websites in the back of my mind.
Tip 1; Start with the outline
Start your article by writing an outline of all the chapters and important topics you want to explain. Gradually add text to flesh out the copy.
Tip 2; Use headings strategically
Headings are essential navigational landmarks in any article. Make sure your headings are descriptive and concise so people can find the section they want to read.
Tip 3; Max line length
The ideal maximum line length in articles differs per font, text size, medium, number of characters, and person.
There have been many studies and articles about ideal line length. I’ve seen numbers in ranges of 40–100 and personally try to stay around 70 characters.
When writing code documentation and READMEs, I use a hard maximum of 79 characters followed by a newline in source code. You don’t see these newlines in the final product, so lines may be shorter in your presentation.
Tip 4; Max number of lines
Keep the number of lines in a paragraph short enough so readers won’t get lost in them, but long enough to not appear puny.
Paragraphs containing between two (2) and four (4) lines should be ideal for explanations. Use single lines for conclusions and statements that you want to emphasize.
Tip 5; Make text easy to understand
Use everyday language where possible and avoid using “big and complicated” words. Make the text as accessible as possible so more people can benefit from it.
There is something called the Common European Framework of References for Languages (CEFR). The so-called CEFR levels indicate a person’s proficiency with a language. I assume that my audience possesses a B-level language proficiency when writing technical articles.
Check out CEFR common reference levels on Wikipedia (external link, opens in the same browser tab) for more information.
Tip 6; Use tools:
Popular writing tools often provide spellchecking; use them! For example, I rely heavily on Ulysses and Grammarly when writing blog articles and Interglot when translating between Dutch and English. (No paid endorsements here)
Take some time to find tools that work for you.
These tips are specifically for documentation presented on the internet inside a web browser.
Tip 1; Provide a table of contents
If you have an extensive article with many headings, provide a table of contents (ToC) on the top of your article. If possible, use a writing tool that generates the ToC for you.
Platforms that host Git repositories often print the contents of a README when exploring a directory in their web interface—tables of content shine here.
Tip 2; Permalink headings
If you have control over headings, make sure people can link to them directly. You can do this by adding an
id attribute to your heading:
<h2 id="hello-world">Hello world!</h2>
Now you can link to that specific heading from any URL, either through a relative or absolute URL:
<a href="#hello-world">Jump to Hello world!</a>
Tip 3; Descriptive link text
Ensure that your links describe their target (the page/document they refer to) even when taking the link out of the surrounding text.
Two of the most popular and worst link texts are “here” and “click here”. Do not use these labels for links as they are non-descriptive.
To make link texts more descriptive, sometimes all you need to do is shuffle words around. See the bad and good examples in the code below:
<!-- Bad link text: --> <!-- "Please get in touch! Click [here] to go to the contact page." --> <p> Please get in touch! Click <a href="...">here</a> to go to the contact page. </p> <!-- Improved link text: --> <!-- "Please get in touch via the [contact page]!" --> <p> Please get in touch via the <a href="...">contact page</a>! </p>
Tip 4; Provide alternative text for media
You can provide alternative text (alt text) for non-textual mediums. Think images, videos, figures, and more.
Alternative text is useful—among other things—when using a screen reader, on slow connections, when using low data mode, or when the link to the source is broken.
There are many articles about writing alternative text which you can check out. Some quick examples of alt text in an HTML
<!-- Bad; missing alt text --> <img src="some-image.png"> <!-- Bad; non-descriptive alt text + redundant word "Image" --> <img src="some-image.png" alt="Image"> <!-- Good; descriptive alt text --> <img src="glass-of-water.png" alt="A long drink glass halfway filled with water."> <!-- Good; empty alt text for decorative images --> <img src="some-purely-decorative-image.png" alt="">
Check out the documentation of each type of HTML element you are using to see how you can add alternative text.
When writing documentation, you should not only think about the information you want to convey: you also need to think about the language, structure, and presentation of your copy.
The writing process is generally iterative as you build your text from an outline to real bits of text and eventually the full copy of your article. When writing for the web, you can also add navigation through links and headings.
Good luck writing your next article!