Technical documents, we’ve all seen them, and many of us might have already discovered how deliciously awful they can be. This blog focuses on improving your technical writing skills for formal / technical documents like policies, standard operating procedures, and work instructions.
What better way to explain technical writing tips than to look into our daily life and see what happens if we aren’t careful when preparing to go out and buy groceries. Are you ready? Let’s jump in!
Which types of documents are there?
There are a lot of different types of documents going around. The first distinction to make is whether a document is formal or informal. You can recognize a formal document through specific properties, such as:
• It has a business impact (for example: describing a process or requirements)
• It has a target audience (operators, IT, …)
• It has a specific use (procedure, work instruction, …)
• Non-conversational/non-casual tone (manuals, reports, …)
• It is reviewed and approved
• It is a structured document
Going back to our daily life example, this is the difference between twenty small notes lying around listing several articles that need to be bought (informal) and the actual groceries list (as you will see throughtout this blog, it ticks all of the “formal” boxes).
How to structure a Technical Document
Let’s say we need ten items from the supermarket:
• Carrots
• Steak
• Toilet paper
• Oranges
• Shampoo
• Sausages
• Chocolate
• Onions
• Cheese
• Toothpaste
Written down like this, you’re going to have fun running around the supermarket, passing each aisle several times because you forgot something. On the other hand, if you list all your items in a specific structured way, you will have a way more relaxed and efficient shopping trip.
Contents of a technical document
Your technical document needs structure too. When you write a procedure, make sure you list all technical content steps chronologically, precisely and concisely, and in plain language. You can also create additional efficiency by having additional sections. In general, each technical documents contains a particular structure, based on required areas, such as :
• A title, which needs to be effective, efficient, clear, and specific
• A table of contents, showing chapters titles and page numbers
• An introduction, which contains the purpose or objective of the documents, as well as its scope
• (Technical) content, depending on the document type (can detail a process, contain operational steps, etc.)
• The document’s history (version number, implementation date, changes implemented throughout its lifetime)
• The approval/audit history (signatures by reviewers and approvers, approval dates, and current status of the document)
Groceries list: check. But what’s missing? Tomatoes! Obviously. But you didn’t notice that you needed tomatoes, so now you’re stuck without any chance to make a delicious soup. How can you avoid forgetting to put things on the list? How about asking your partner, your children, or any other stakeholders?
Reviewing your technical document
This would be the process we call reviewing, in other words, making sure that everything you need is in your technical document. Different parties can perform this review: subject matter experts, the quality assurance department, the IT department, …
Summarizing: all stakeholders should look at the document and examine if it meets all requirements and is complete.
Once everyone has had their say, and you made all necessary corrections and adaptations, you can submit your grocery list for approval. You are now ready to go to the supermarket and get those much-needed supplies.
Optionally, other information might also be added to your technical document, depending on whether it is helpful to have it or not:
• Roles and responsibilities of people involved (author(s), reviewer(s), Quality Assurance, involved department(s), etc.)
• A list of abbreviations and definitions
• Headers and footers
• Attachments (including a list of attachments, such as large visuals and additional information)
• References to literature, sources, and related documents
• Environmental, health, and safety advice/precautions
Take another gander at the list of needed supplies above. How did you write down the items? Were you clear? Did it leave room for interpretation? Sometimes, when we’re in a hurry, we might start cutting corners, which may also show our writing quality. What would you buy if the groceries list contained abbreviations, such as:
• TP: 2
• C: 3
What would you instead end up forgetting, toothpaste or toilet paper? Chocolate or cheese?
Abbreviations save us time, yet they might end up confusing us instead. Ensure that the document containing abbreviations also clarifies them, either in a separate section or in line with the text.
Adding layout to your technical document
Why would you want to add layout to a document? We all enjoy a bit of prose now and then, don’t we? Nothing wrong with a wall of text. Unless you want a smooth read of course.
Imagine your grocery list to look like this, all jumbled up.
This is why we add layout to a document. More specifically, because of layout:
• Enhances understanding and readability
• Clarifies differences in primary and side points
• Supports the structure of the document
We propose the following guidelines:
• Neutral and readable font style (so no Comic Sans, thank you very much)
• Use paragraphs
• Spacing between lines and paragraphs
• Text alignment
• Text indentation
• Use bullet points (just like we did right here)
Good writing skills for technical documents
Of course, while writing any document, keep in mind:
• Logical flow from one paragraph to the next
• No grammatical or vocabulary errors
• Use a suitable technical writing style
To illustrate this last point with our groceries list: let’s introduce two scenarios where your partner or any other type of housemate tells you about their need for oranges (they are “the procedure” in this example), and the consequences, based on how they convey the message:
Scenario 1: You should buy oranges.
Possible result 1: I should’ve bought oranges, but I purchased apples instead
Possible result 2: I should’ve bought oranges, but I didn’t
Possible result 3: I purchased oranges
Scenario 2: You must buy oranges.
Possible result 1: I bought oranges
Which do you think is the more secure and trustworthy option? If you picked scenario 2, you’re on the right track. If you chose scenario 1: we wish you luck with all the stuff you don’t need.
What we’re trying to bring across here is to choose your words carefully. Write a technical document of any kind. There should be and must be no room for interpretation as long as we’re talking about technical content, operation steps, requirements, etc. Of course, the interpretation might be necessary when you’re making a certain conclusion for research or a report based on gathered facts.
You see, sometimes it’s in the small nuances, such as the words “should” and “must.” This is just one example to take into consideration. Which others can you think of?
In a nutshell
In this blog, we gave you some tips on how to write technical documents more efficiently. In any case, let’s summarize the subjects we handled:
- Types of documents
- Structure
- Layout
- Adding the finishing touches
By taking these rules into account, you’ll go a long way. We wish you good luck!
Hungry for more? We have plenty of tips on how to become an expert at technical writing. Check out our training courses on the topic.
