How to get started with technical writing

This blog post is about an important topic in engineering jobs. It is about doing your paperwork, the documentation, the (technical) writing. This is something science and engineering have in common: Without proper documentation, your work can easily become unusable and/or meaningless. In the era of self-explaining and explorative user interfaces, proper code documentation, project reporting, written design decisions and architectural explanations mark the difference of high quality work and unmaintainable "single-use projects" with limited lifespan.

The web is full of advices how to write. Don't think to write, write to think is an article I just read today. Ironically, in the era of Covid-19, video conferencing and remote work, the written word becomes once more very important in particular in the context of protocols, digital meeting artifacts and chats and short messages. And yet many developers have a natural resistance against bringing their thoughts to the sheet (or the screen). Since I am somewhat the house poet of DenktMit eG, I feel somewhat obligated to add my thoughts to the pile of tips.

Getting started: Overcoming barriers

Many people (including me!) have problems entering a big illumnated stage and start giving a keynote. The more you think about it and prepare for it, the bigger the problem can get. What is the textual correspondence to stage fright? Probably sitting in front of a big white paper, either physical or in form of MS Word or your favourite text editor for code (documentation).

There are different strategies how to cope with that. Do you remember what you do when starting a new coding project in a new programming language from the scratch? You never start with an empty document. There is always some tutorial, some demo code which you can build up on. It is the code equivalent of a textual outline, a table of contents. Start with your favourite note-taking app and write down some bullet points of what you want to write about. Do some nesting and voila, you are done with a table of contents. Did you notice that I suggested you do this work in your regular note-taking app (suggesting that you have such a thing, like Evernote, Notion.io, Apple Notes, Google Keep, Microsoft OneNote, etc.)? If you don't have such an app, why not take some other familiar environment such as your e-mail client or some chat window with a friend? This is somewhat similar to training your big keynote show act in a familiar environment in front of your best friend.

Improve iteratively

Something else you probably naturally do when changing situation is making use of your everyday voice. No need for pretending a vocabulary which is not yours. If it helps, talk and write colloquially! Even when you want to set high standards on your text, it is better to get started with a bad text then with no text. The same is true for language: If you want or need to write in English but are much more fluent, say, in German, then write down a German text. Machine learning translation (such as with Linguee/DeepL) got very good in the last years even in highly technical texts and can be a great starting point when doing the language transition.

When it comes to iterating texts, forget about formatting technicalities for the moment. Exclude correct hyperlinking, footnotes, citations, images, headings, everything which makes text complicated. If it helps, also skip all your fancy versioning tools (such as git) or the correct markup (such as Latex, HTML or markdown). Just work with plain text, which is most interoperable between your tooling. This makes it easy to copy and paste to Microsoft Word in order to quickly run spell and grammar checking. You want to come into a mood where you really work with text the same way as you do cooking: Words and sentences are your ingredients and subject to be cut here and there, put into form, being rearranged, temporarily deleted and retrieved again.

Know your audience

Something you should consider while improving your texts is asking yourself who is the target audience and what questions you want to answer. Sure, these are questions which are relevant to answer before writing a text, but why not improve while iterating over your texts. It is quite likely that you recognize you can make two texts from one starting point.

If you wonder about the audience, here are a few good starting points: Think of yourself but before the project started. What questions would you like have to be answered? Or ask team mates, friends and/or coworkers for what questions they would raise about your project.

Writing is not that different to coding

In the end, a good technical writeup shares quite some details with good code: It is concise, answers a particular question by using a particular vocabulary. It is typically highly structured. References of various kinds, a glossary, good searchability are vital to code documentation or a good scientific paper. Since you are probably used to formal methods such as a computer programming language or the mathematical language of your specific scientific problem, why not treat your documentation similarly formal? Sooner or later you will find a way of how you would like to read literature and be able to replicate that style on your own.

Epilog: Making money with writing

I have to admit that I spend a good portion of my day with writing texts. Let it be proposals or reports, there is always a majority of text which replicates previous work (done by me or others) and only a minority of novel ideas. Most of the time when I start a new text, I do it by copying some old one, deleting all text and building up on the template, thus seldomly starting with an empty page or empty line. But from time to time I also enjoy writing a LaTeX document from the scratch or exploring all the features of a new code documentation system (something like Javadoc). I am kind of a agnostic purist, not into emacs or vim but just using any plain text editor available on the system (such as gedit, kwrite, notepad++) which has low background noise (no distraction). But most of all, I enjoy writing texts in a single run, from a single cast. This gives them a rather spontaneous note, and it is in fact the same way as I handle my stage fright: I just start talking, without much preparation, and evventually come to an end.