Consistency in terminology is important in technical writing. Each word or phrase must be consistent in spelling and usage throughout a document. Unlike in creative writing where synonyms are used to avoid repeating the same word, in technical writing, it is considered good practice to repeat the same word in order to maintain consistency.
Why is consistency important?
It's simple—adhering to the same rules throughout a document improves the coherence of your overall message. Repetitive patterns in content organization generally make it easier for the reader to navigate a document and quickly locate a topic. More importantly, repetition reinforces learning.
Additionally, if the content you create needs to be translated into other languages, consistent use of terms can make the translation process easier, faster, and less expensive.
Here are some tips for using consistent terminology.
1. Don't use the same word to refer to two different concepts.
Consider the word “interface”—when used as a noun, it can mean the graphical user interface of a software application, and when used as a verb, it can mean interacting with another person, organization, or a system, depending on the context. In a user manual for a software application where you use “interface” often as a noun, do not use it as a verb too—instead use “interact”.
The following example demonstrates how using the same word to refer to two different things can create confusion for a reader.
Example (ambiguous sentences): The current system for document management needs improvement. The new system that will be implemented will automate the document management process and improve the workflow.
Although the example shown above uses grammatically correct sentences, they can convey the wrong meaning if the reader is not aware that in the first sentence, system refers to the current workflow, and in the second sentence, system refers to the new software application that will help automate the workflow. Now read the clear sentences below.
Example (clear sentences): The current workflow for document management needs improvement. The new electronic document management system that will be implemented will automate the document management process and improve the workflow.
2. Avoid using different words interchangeably to mean the same thing. This is especially important if the words are close in meaning as it can increase the reader's confusion.
Example:
- Workflow and Process flow
- Command and Option
- Icon and Button
3. Always follow the manufacturer's guidelines when referring to trademarks and registered products.
Example:
- AutoCAD® Map 3D
- CATIA™
- SolidWorks®
- Autodesk® Vault Professional 2023: Data Management for Autodesk® Inventor® Users
4. When referring to product-related terms, be precise and use them exactly as they are used in the product.
For example, in software training documentation, when referring to elements on the interface, such as menu items, fields, dialog box names, buttons, and tooltips, use the spelling exactly as displayed on the screen so that it is easy for the reader to relate.
A term like "Quick Access Toolbar" in Autodesk Inventor is referred to as "the Quick Access Toolbar" in Autodesk Help. Notice the capitalization and the use of "the" before the term. When you refer to that toolbar in your documents, follow the same guideline and do not use "Quick Access toolbar" or "Quick access toolbar" or even just "Quick Access Toolbar" but "the Quick Access Toolbar".
Provided below are two examples of instructions that demonstrate how terms have been used exactly as they display on the user interface.
Example 1:
In the figure shown below, notice the name of the dialog box and its capitalization. Even though the capitalization appears incorrect, in your instruction, you must use the dialog box name exactly as it displays on the interface because that is what the readers will see on their screen too.
In the Browse the vault For Folder dialog box, select the Content Center Files folder and click OK, as shown in the figure below.
Example 2:
In the figure shown below, notice the name of the option (keep Both sides).
As in the previous example, the capitalization appears incorrect. However, in your documentation, you must use it exactly as it displays on the screen, as shown in the instruction below.
In the Specify a point on desired side prompt, select the keep Both sides option to keep both sides of the object.
5. Only use words that are in a standard dictionary and can be easily understood by your readers.
Some portmanteau words (words made from blending two different words), such as edutainment (education + entertainment), netiquette (Internet etiquette), or favicon (favorite icon), may be used in specific styles of writing, such as blog posts or magazine articles. However, it is better to avoid such words in technical writing.
If you could use the assistance of a technical writer for your next project, please reach out so we can discuss your project needs.
About the Author
Follow on Linkedin More Content by Surya Nair
