When authoring specifications, technical documentation or articles, many pitfalls wait for authors (and, as a consequence, their readers) — but there are ways around them. In this post, I’ll highlight a few frequently made mistakes by example and suggest improvements.
Examples of the advice I often give to students (and peers and myself) include:
- Know your audience and write for it, not for yourself. If you struggle to identify it, create personas just like you do in software development and user interface design.
- There is no such thing as an unordered list in technical writing (to paraphrase a hint by Gregor Hohpe). Decide the order of enumerations, table rows, sections, and chapters consciously: importance, time, or logical flow are suited ordering criteria.1 Alphabetical order makes a good default. You might want to explain the ordering scheme to your readers unless it is obvious.
- Avoid excessive use of TLAs.2 If you use TLAs, do introduce them. A rule of thumb from my OST colleague Katharina Luban is:
if [TLA usage > 5] then [introduce and use TLA] else [use long form only]. - The passive voice should be avoided. Oops! Of course I meant that many technical writers prefer the active voice over the passive voice — most of the time. Sentences are made ambiguous and fuzzy by using the passive voice: who causes the action here? The active voice promotes qualities such as clarity and expressivity. The passive voice has its place, though: sometimes the actor is not known at all; sometimes the actor deserves the main focus, but you want to establish the context and topic before introducing it to improve logical flow from the previous to the current sentence.
- Do not turn verbs into nouns by accident. For instance, “I want to compose services” is less loaded than “I want to perform a service composition”. So please avoid nominalization, or much clearer: do not nominalize verbs. Steven Pinker calls these “Zombie nouns” in this recorded lecture that provides much more invaluable advice.
- Prefer strong, domain-specific verbs that are part of the ubiquitous language of your work over weak, generic ones. When talking about blogging, for instance, you “author”, “review” and “post” articles, rather than “make”, “do”, or “perform” things. The same rule of thumb applies to nouns (but is a little less critical there). For instance, how do component names such as “Client” and “Server” compare to “Shopping Web App” and “Online Grocery Store”? Or the file names
thesis.pdfandmain.javatoHSR-BachelorThesisA1A2-ServiceCutter.pdfandABC-WebShoppingApplication.java? - Design the bibliography carefully along the structure and content of your document, and lay it out consistently. Adjust and tailor it according to wants and needs of your target audience (and publisher). For example, some URIs to blog posts and Wikipedia articles typically are ok to provide background information, but will not be sufficient in scientific writing where you are expected to cite and critique peer-reviewed papers and must meet various review criteria for research papers. If you have many references and write multiple related documents, let tools such as BibTeX or EndNote assist you.
These are really just examples, not necessarily the most critical mistakes. I picked some less obvious ones for this post that inexperienced writers often get wrong (and that I observed recently). There are many more things to watch out for, and we all shall practice our technical writing deliberately. My next post on technical writing, How to Write Review-Friendly Articles, discusses more tips and tricks, and provides links to additional information such as a free PDF book (in German), a video lecture and related posts.
Another follow-up post introduces a shorthand notation and markup for speedy meeting minutes and reviews.
You also might want to check out this post by Méline Sieber: “Writing Well”.
I hope you find these tips and trick useful. Let me know when you would like to contribute some of yours. Thank you Gregor Hohpe for the shoutout on LinkedIn!
– ZIO