how to write a technical document — my top ten (10) tips
I do a lot of technical writing. I was a scientist for 10 years, and productivity in that profession is measured nearly totally in number of publications. After that, I managed a product engineering department for 7 years and that involved all kinds of reports, technical in one way or another. Now as a freelancer, recently I have been rewriting the MCS product and installer standards covering micro-CHP domestic heat and power appliances.
While I am now confident at writing technical documents, I realise I was never trained at it. Many of you could be in the same situation of having to learn by doing, so, from my lifetime experience what advice could I offer to someone wanting to become a better technical writer?
1. Keep in mind the end user of the document
Your target audience will define your style, tone, formatting and content. For instance, in scientific writing I use complicated science concepts and terms but for the sake of non-native english readers (who are the majority of scientists) I otherwise avoid uncommon words, metaphors and particularly long sentences.
When I am writing technical standards, there are usually common set phrases and words and these I will repeat throughout the text in order to get the reader familiar with them. There is no simplifying the use of this language especially when its specifically legally worded so you must instead guide your readers to familiarity through repetition.
In technical reports where I have some creative control of the look of a document, I use formatting of the document to help understanding. With the correct placement of information I can associate pieces of information without specifically mentioning it, give the reader more information at a glance and highlight the important information by putting it in the centre of the page.
The worst technical documents are those that don’t prepare the reader for what they are about to try to understand. A bad example of a technical document I have seen is the ‘UK Standard Assessment Procedure for Energy use in Domestic Dwellings’ (called the SAP for short). I have to use this document a lot, and its hard work, like building Ikea furniture.
2. The stakeholders must be pleased
On top of your target audience, you have to understand the motivations of the stakeholders that want (or sometimes don’t particularly want) the document to be created. Each stakeholder will be paying time or money to help make the document so every stakeholder will want to content with the final result. It is the large number of people who have to contribute to technical writing and be happy with it, that is perhaps the hardest part of technical writing.
3. Separation of facts and opinion
Every scientist is in love with their latest finding, and therefore will always think everything they do is front page news. Minor new frog species discovered, “very interesting”, tweaked the gravitational constant to the fifth digit, “very important”, increased the dial to 11 on the guitar amp, “very significant”. This can lead scientists to try too hard to sell their discovery and to mix their opinion in with their factual findings. This hampers the writing of the document, hampers the reading of the document, and eventually discredits the result however credible the evidence. Nearly all my first drafts of my own manuscripts have this flaw, and I have to edit it out later. Likewise, I have edited several other scientist’s manuscripts and had to face their anger for removing their (over-) enthusiasm from a write-up of their results.
Thankfully, scientific papers are usually separated into different sections by convention; Results, where you talk about your observed results and nothing else, Analysis, where you analyse your results with respect to the current state of the art highlighting what you have found that is new or useful. Finally at the end of the paper, there is usually a chance to relate the importance of your finding and here you can speculate about what you might think might be happening before you wrap-up with your conclusions. This structure means that in nearly every scientific report you can always avoid opinion and just read the findings.
4. Respect technical words
In technical writing you will use technical words with specific meanings. These should be used at the right time and must be protected from loose or broader usage. In this respect English is a good language for technical writing as it offers so many other choices of words.
5. Use acronyms less often
Writers go through a phase initially of loving acronyms for the hassle saved in writing and will include them everywhere and anywhere. However, good technical writing is not about the writer enjoying the writing but for the reader to enjoy reading (well, at least not throw it against the wall in frustration). The easier it is for the reader to read at their natural pace the better and a long-list of acronyms doesn’t do that. Where you use a phrase often enough it makes it worth-while investing the reader in an acronym, then do so on the second or third usage. Waiting until the second or third time allows the reader more time to put the phrase into context and memory.
6. Worked examples
Worked examples are fantastic at improving your clarity of writing as you are forced to compare your written instructions with what you actually do in practice. For the reader, not only will they appreciate the clearer text, but by running through an example there is a chance for them to find and correct their own mistakes. On the down-side, worked examples are time-consuming to make and if you even slightly don’t know what you are writing about you can’t make them at all.
7. Mathematical equations
Some people can understand math equations intuitively. However, some people can’t read math equations, and some math equations are beyond even capable and experienced readers. A verbal description, even if incomplete, will help explain how the math equation was formed. If you have an equation chances are a worked example might help.
8. Use Plain English
While you should write in as simple English as possible, you should also match the writing style of the organisation for whom you are writing the document. Naturally, the organisation must be able to recognise and accept the document you have written (see pleasing stakeholders above). Sometimes an organisation’s style goes against writing in plain English and this is where you need to show good judgement. The organisations documents might be difficult to understand in general, but at least you can try to make yours a little less difficult.
9. Your own opinions don’t matter
In personal writing your opinion is the only thing that matters but in technical writing it doesn’t matter at all. It’s great to be passionate about the process but distance yourself from the outcome. You have to put into words a fair reflection of what the stakeholders wanted.
10. Technical writing for entertainment/blogs etc
True technical writing should be complete, in that it presents all the arguments and facts worth presenting. Technical writing for entertainment however should include only the most convincing reasons with any minor reasons excluded. This is due to the dilution-effect where the adding of further but less important points leads to lowering the perceived value of the argument. In technical writing for entertainment you are trying to inform, entertain and be convincing, so you should stick to your most exciting material.
