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.
Tip 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.
Tip 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.
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 the source code. You don’t see these newlines in the final product; hence, lines may appear shorter in your presentation.
Tip 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.
Tip 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.
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.
Tip 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 leave a dent in their self-esteem.
Tip 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 (external link, opens in the same browser tab).
Tip 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>).
Tip 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.
Tip 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.
Web tip 1: Provide a table of contents
If you have an extensive article with many headings, provide a table of contents (ToC) at 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.
Web tip 2: Permalink headings
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>
Web tip 3: 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>
Web 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 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, you should 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
2021-09-27:
- Added
Tip 7: Avoid down-talking your audience.
2021-10-26:
- Added
Tip 8: Do not mislead readers.
2022-07-21:
- Added
Tip 9: Go easy on the abbreviations. - 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.
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.