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.
Structured
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.
Accessible
For any documentation accessed by non-technical people, send them a PDF or better a link which ideally includes search capabilities and easy ways to switch between versions and languages if needed, instead of pointing them at a code repository.
Nowadays many flat file-based CMS exist that can quickly turn your markup-files into indexed content. Some editors like Emacs org-mode also allow quick direct export of single documents.
Easy to Edit
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 makes 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.
This is best done manually when writing, as automatic pattern-matching may 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. If you are converting an existing document, a tool like https://waldyrious.net/semantic-linebreaker/ can be helpful.
Terse
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. Though because multiple participles can be hard to read, being aware of both is helpful in case of multiple verbs within a sentence.
Some words to avoid are "can" and "need" and "should", as well as the German "man". Each of these can be removed without loss of information, making the document more terse.