Technical Writing 101: Terms listSeptember 15, 2011
Whether it’s a report, a Help file, or other lengthy business or technical document, you’ll probably need to provide a list (or glossary) that defines all the terms — abbreviations, words, phrases — that you’ve used in the document that are NOT familiar to your audience.
Of course, determining what is and isn’t ‘familiar’ (or common knowledge) to the readers of your document is a bit of a black art and will depend on your expected audience. For an engineering document written only for engineers (substitue your area of expertise for ‘engineering’), you wouldn’t need to define every engineering term that ALL engineers should be familiar with. But if your document is also likely to be read by people who aren’t engineers (e.g. government regulators, general public), then you’ll have to define the engineering terms in your terms list.
What goes into a list of terms? These at least:
- unfamiliar and/or ‘industry jargon’ words and phrases (be aware of your audience and only include those that are likely to be unfamiliar to them)
- abbreviated units of measure (e.g. ppbv, kPa, ha) Note: While you may be familiar with particular units of measure (e.g. mm, cm, t, kg), be aware that readers in other parts of the world, such as the US, may use a different measurement system
- abbreviations, acronyms, and initialisms (e.g. LNG, CSIRO, UNICEF, EPA; see http://grammar.quickanddirtytips.com/acronyms-grammar.aspx for the differences between these).
When writing your document, always write out in full any abbreviation/acronym/initialism the first time you use it in the document – e.g. Environmental Protection Authority (EPA). After that first instance, you can use the abbreviation/acronym/initialism (e.g. EPA) throughout the rest of the document.
[Link last checked July 2014; based on a Writing Tip I wrote for my work colleagues]