Writing Good Technical Documentation

I love writing, even technical. And I am a perfectionist. This leads to me regularly hitting edit while reading through a README file or the like because adjustments jump at me. In this post, I want to share some of my lessons and recommendations from doing this in the last years.

First of all, use structured markup - Markdown, AsciiDoc and Orgdown are some standards I am familiar with. The important part is that it is plain-text based so it is accessible even without any special software, and the markup is machine-readable.

Office documents are not a good fit for either, and they pose a lot of unneccessary choices like typography and font size, formatting templates and more. Those can be handled separately (saving the time of those with technical expertise) when wanting to typeset the document. Any of these formats has a plethora of tools to convert them to a webpage or a PDF and a lot more, the most prominent being pandoc.

This conversion I recommend for any documentation that should be accessible to non-technical people, so that rather than pointing them at a code repository, send them a PDF or better a link which ideally includes search capabilities and easy ways to switch between versions and languages if needed.

I do not want to dwell on this too long, because https://sembr.org already conveys the point well, as a natural progression from the "One Sentence per line" paradigm. Either make it much easier to apply and check corrections because diff algorithms work best on a line-by-line basis. I never saw the advantage of limiting lines by characters when any editor nowadays can do that automatically on display, adjusted to the needs of the person working with the text.

The good thing about Semantic Linebreaks is that, applied well, they can even show you troublesome sentence constructs, visualize the structure of an argument and shorten lines thus that they never need to be wrapped either. You can also easily comment out or remove part of an argument.

The only thing here to keep in mind is that this is best done manually when writing, as automatic pattern-matching will produce linebreaks in the middle of enumerations, which I personally do not want. But as somebody in the habit of it this takes no extra effort at all.

With the basics down, we come to the point where I tend to apply little adjustments most often: Phrasing. This is a delicate point because I understand most people do not write in English as their mother tongue (neither do I) so suggest gracefully. Yet learning to cut down on unnecessary phrases can elevate your writing to another level.

Let me lead with a common example:

 To run the tests you definitely need to install somelib.	  

This contains multiple redundant piece of information:

• "you" need to install it - well, who else? And maybe it is not even you but your Ops-Team, so this may turn out to be a false assumption. Either way, you as writer should not be concerned with who does what.
• "definitely" - any kind of intensifiers are usually out of place in technical writing
• "need to" - this appears in different variants and is superfluous, as the verb already communicates the need

 Installing somelib is required to run the tests.	  

What about this? This sentence makes sense if you are explaining the use for different dependencies. But if you want to explain how to run the tests, start the sentence with that, for example:

 Running tests requires somelib.	  

OR

 To run the tests, install somelib.	  

By putting the purpose of the action first, it is easier for the reader to skip to the parts they need. Whether to use the infinitive or the participle here seems a matter of taste, being aware of both is helpful though if you have multiple verbs within a sentence because multiple participles can make it hard to read.