Technical documentation writing quick tips

(last update at ) — 1455 words

This article is part of a series:

Writing documentation Tips and tricks for writing documentation for code projects.
  1. Why you should and should not write code documentation
  2. Technical documentation writing quick tips
  3. Quick tip: Formatting unordered lists in plain text
  4. Remove hard line breaks from READMEs

Below are several quick tips to help you make your technical documentation (docstrings, READMEs) more accessible 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; this “quick tips” article serves as an everyday primer.

Important: This is a living document.

General tips

These tips should do well for any medium, but I keep websites in mind.

1: Start with the outline

Start your article by outlining all the chapters and important topics you want to explain. Gradually add text to flesh out the copy.

2: Use headings strategically

Headings are essential navigational landmarks in any article. Ensure your headings are descriptive and concise so people can find the section they want to read.

3: Max line length

The ideal maximum line length in articles differs per font, text size, medium, number of characters, and person.

Many studies and articles have been written about ideal line lengths. I’ve seen numbers in the range of 40–100 and personally try to stay around 70 characters.

4: Max number of lines

Please keep the number of lines in a paragraph short enough so readers won’t get lost but long enough not to appear puny.

Paragraphs between two (2) and four (4) lines should be ideal for explanations. Use single lines for conclusions and statements that you want to emphasize.

5: Make text easy to understand

Use everyday language, and avoid “big and complicated” words. Make the text accessible 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 my audience possesses a B-level language proficiency when writing technical articles.

For more information, check out CEFR common reference levels on Wikipedia (external link, opens in the same browser tab).

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.

7: Avoid down-talking your audience

People read your article to inform themselves about something they don’t know yet. Avoid down-talking your readers by leaving certain words out of your text.

Don’t tell readers that what you’re teaching them is “easy,” “beginner,” or “simple” if it is not (and even if it is, be careful); otherwise, you will damage their self-esteem.

8: Do not mislead readers

Ensure your reader understands your article’s context as soon as possible. When you publish an article burning down a particular product and then present the reader with an alternative of your own, that’s secretly an advertisement—this strategy hurts your credibility.

There is nothing wrong with wanting to sell a product or service, but make sure your readers know what they’re getting themselves into.

Note: This tip draws inspiration from Roland L. Taylor’s tweet about an ad masquerading as an article (the tweet has since been removed).

9: Go easy on the abbreviations

Much like jargon, abbreviations are hard to understand for those who aren’t experts on the related topic. Avoid the use of non-generic abbreviations where possible.

If you use an abbreviation, introduce it early in the article alongside its expanded version. You can utilize a pattern like <full name> (<abbreviation>).

10: Use contractions consistently

We often shorten words in informal speech and written texts, where part of a word gets replaced with an apostrophe.
For example, "I am" becomes "I'm," and "cannot" becomes "can't."

In English, these shortened words are called contractions, and are often combined with auxiliary verbs.

Pick between contracted or uncontracted styles, and stick to them. It will make your text look more consistent.

Note: You may face similar choices in other linguistic patterns depending on your writing language. For example, T-V distinction.

11: Use line breaks strategically

Even if you stick to a maximum length (see Tip 4 above), lines can sometimes contain too much information. It could also be that a sentence wraps to the following line in an unfortunate place.

When two sentences should be in the same paragraph but do not look good on the same line, consider using a line break (<br> in HTML) to put the second sentence on a new line.

Some people apply semantic line breaks, where you put each new unit of thought on a new line. Others prefer to put each new sentence on a single line. In poetry, this technique is called lineation.

I am not a fan of enforcing either technique, but they have their merits when used strategically. Remember that using line breaks only partially in texts could look inconsistent and have adverse effects.

Note: I did not figure this out on my own. See my original question about the name of the semantic newline writing technique.

Web-specific tips

These tips are specifically for documentation shown in internet browsers.

W1: Provide a table of contents

Provide a table of contents (ToC) at the top if you have an extensive article with many headings. 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.

If you control headings, ensure 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>

W3: Descriptive link text

Ensure your links describe their target (the page/document they refer to) even when reading it without context.

Two of the most popular and worst link texts are “here” and “click here.” Please do not use these words 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>

W4: Provide alternative text for media

You can provide alternative text (alt text) for non-textual mediums, such as images, videos, figures, and more.

Alternative text is helpful—among other things—when using a screen reader, on slow connections, 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<img> element:

<!-- 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 the HTML element you use to see how to add alternative text.

Wrap-up

When writing documentation, consider the information you want to convey and 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. You can also add navigation through links and headings when writing for the web.

Good luck writing your next article!

Changelog

2024-11-11:

  • Removed the unnecessary word "Tip" from all the headings.
  • Removed mention of a README line break strategy from 4: Max number of lines, as I no longer do this.
  • Restored a missing Wikipedia link to CEFR in 5: Make text easy to understand (hat tip to Sander van Kasteel).
  • Improved wording throughout the article.

2024-08-10:

  • Removed the link to a since-deleted tweet.
  • Improved wording throughout the article.
  • Changed the order of the changelog items from newest to oldest.
  • Made the changelog dates bold.

2024-02-11:

  • Added Tip 10: Use contractions consistently.
  • Added Tip 11: Use line breaks strategically.
  • Reversed the changelog order to the oldest change first.
  • Switched semicolons for colons in headings.
  • Improved wording throughout the article.

2023-05-21:

  • Converted tip headings to use HTML heading elements.
  • Renamed “Tip” to “Web tip” where applicable in headings.
  • Improved wording throughout the article.

2022-07-21:

  • Added Tip 9: Go easy on the abbreviations.
  • Improved wording throughout the article.

2021-10-26:

  • Added Tip 8: Do not mislead readers.

2021-09-27:

  • Added Tip 7: Avoid down-talking your audience.