How to write technical documents. A basic outline of styles and technics used in technical writing. A beginner's guide.
This article is not intended to replace a full Technical Writing course. It is offered as a quick and dirty guide outlining the basic techniques and styles used within the technical writing field for people who do not normally write technical documents.
For clarity and ease of use I am breaking this information into 5 articles that cover the basic techniques used in Technical Writing including:
• Knowing Your Audience
• Top Down Structure
• Writing Clear Sentences
• Being Concise
• Using the Active Voice
In the first article I discussed Knowing your Audience. The techniques a technical writer should use before starting the writing process. So now you know who you are writing for and the purpose of the document. You're sitting in front of your computer, ready to start writing, but there is one more technique you should know before you start:
Top Down Structure
Top down structure simply means putting the main point first. After the main point comes the supporting information. This technique is not unique to technical writing; it is also used in newspaper articles and in most essay writing. Top down structure can be applied to all levels of writing from the document as a whole right down to individual sentences.
Visualize a triangle with one point at the top. The point of the triangle represents the main point; small ,precise, to the point. If you move towards the bottom of the triangle the base gets wider. This represents supporting information and increasing details. The more the user reads, the more information they will receive.
In example one, top down structure has NOT been used. How much of the paragraph must the user read before they find the purpose of the Test Chamber?
The Test Chamber is located in a large test room. The Test Chamber can reproduce pressures between 0.2 and 1 bar (abs) and temperatures between minus 20°C to plus 80°C. The Test Chamber is used to control air pressure and temperature around the widget to simulate altitude conditions. The temperature of the test room can be controlled between minus 20°C and plus 35°C.
Example two is the same paragraph with the top down structure applied:
The Test Chamber is used to control air pressure and temperature around the widget to simulate altitude conditions. The Test Chamber can reproduce pressures between 0.2 and 1 bar (abs) and temperatures between minus 20°C to plus 80°C. The Test Chamber is located in a large test room. The temperature of the test room can be controlled between minus 20°C and plus 35°C.
There are two reasons to use the top down structure in technical writing.
1) Easy to Navigate:
By having the main point first, the user can quickly scan a section of information and determine if this is the information they need. They do not need to read four or five sentences before they get to the heart of the matter. If they are scanning large sections of a document, the four or five sentences can add up quickly. In the given example, a quick scan would tell the reader that the paragraph is about the Test Chamber. If they are not looking for that information they stop reading after the first sentence and move on.
2) Reader Only Reads What they Need
The reader gets to the main point right away and can stop reading once they have the information they need. Again, most people do not read technical documents for fun. In the example, if the user simply needed to know what the test chamber was for, they can stop after the first sentence. If they needed to know the temperature or pressure ranges of the chamber, they must read further. If they also need to know where the test chamber is located they will read the entire paragraph.
Top down structure is a very simple principle but it is vital for technical writing. Without this structure, the end user would be forced to read entire technical documents to find the information they need. The reality is that no one is willing to do that. Your document might have the best information ever written about a particular subject but if it isn’t easy to navigate or if the information is buried under loads of other information, no one will read the manual.
If no one is going to read the manual, there is no point in writing the manual.
The third technical writing basics article will cover the techniques used in Writing Clear Sentences.
Figure G-15. Formal sentence definitions: their components are the term being defined, the class it belongs to, and its distinguishing characteristics.
Take particular care when you write the reference to the class to which the term belongs; it sets up a larger frame of reference or context. It gives readers something familiar to associate the term with. The term may belong to a class of tools, diseases, geological processes, electronic components; it may be a term from the field of medicine, computer science, agriculture, reprographics, or finance. Avoid vague references to the class the term belongs to: for example, instead of calling a concussion an "injury" or botulism a "medical problem," call them something more specific like "a serious head injury" and "a severe form of food poisoning," respectively.
Similarly, provide plenty of specific detail in the characteristics component of the formal sentence definition. Readers need these details to begin forming their own understanding the term you are defining.
Be aware, however, that your formal sentence definition will likely contain additional potentially unfamiliar terms. Somewhere in your extended definition, you'll need to explain them as well, possibly by using short definitions (explained later in this section).
Figure G-16. A formal sentence definition used in an extended definition