A controlled vocabulary (CV) is a language with a limited set of words and strict grammatical rules designed to improve technical communication by making it easier for documentation users to understand and apply what is written correctly. There is no definitive right or wrong as
to when to use a CV for a technical writing project. Many times the decision is made based on the complexity of the project, whether or not translation is required, and the costs involved to implement and maintain the CV.
Regardless of the decision, best practice guidelines for technical documentation authors should always be followed:
- Use words that have a precise meaning
- Use the abbreviated, simpler form whenever two or more forms of a word are acceptable
- Use different words for different actions
- Be specific in defining a role versus a person
- Once a clear and convenient way to express a concept is developed, use the same phrase whenever the same situation is encountered
Consistency is one of the most important concepts in technical writing and knowledge management. CVs simplify active knowledge at work for subsequent retrieval. They are used in subject indexing schemes, subject headings, thesauri, taxonomies and other forms of knowledge organization systems. Since CVs have stricter rules than the general language, they enable authors to write consistent source text that is more understandable. Understandable text is also easier and more cost effective to translate.
Source text that isn’t consistent and isn't used consistently can be confusing. More importantly, it can become a safety risk. For most technical documentation projects, using a CV simplifies organizing information and ensures consistency. Arguments against using CVs are that they can quickly become outdated, require too much time to monitor, and can be too costly to maintain.
Text types suitable for using a controlled vocabulary include:
- Technical documentation
- Technical reports
- Technical specifications
- Software strings
- Help systems
Benefits of using a controlled vocabulary include:
- Quality assurance and improvement
- Improved safety
- Standardized way of writing
- Facilitates XML, structured authoring (Information Mapping, DITA, S1000D), content management
- Cost effective, faster, and better translations
- Improved customer experience
Liabilities associated with not using a controlled vocabulary include:
- Damage during operation or maintenance
- Safety risks
- Liability claims
- Confused and frustrated readers
- Higher training support costs
- Unsatisfactory translations
- High localization costs
- Ineffective customer service
7 Tips for Constructing a Controlled Vocabulary
Your CV can be as simple as a short list of terms or as complex as a thesaurus containing thousands of terms with a hierarchical structure and multiple relationships among the terms. When you begin construction, your initial goal will be to plan your strategy for developing a CV designed to help the user locate key information in the document that is consistent in both scope and how deeply topics are covered, agile, and easy to update.
Follow these seven tips when constructing your CV to make sure that it accurately reflects your goal:
Develop a strategy. What do you want your CV to do?
Start gathering terms. What are the terms used to describe your content?
Establish preferred terms, variants, and hierarchies. How do the pieces fit together?
Establish a record of the rules you are using. This is especially important if you are creating a large thesaurus. It will allow you to maintain consistency as your CV ebbs and flows.
Implement. Here's where you'll need a good rapport with your IT people.
Test, evaluate, and refine. Check it out. Then, let your friends do the same. What can be improved?
- Maintain. To keep a CV viable and usable, constant monitoring, evaluation, and tweaking are critical. Think of your CV as a work in progress.
Because CVs exists to serve their users, both those who employ them to describe content and those who use them to locate needed information, it is essential to conduct periodic tests with follow-on evaluation to make sure each CV is as useful as possible. It is also important to realize that to be effective, a CV needs regular maintenance. A well-maintained CV will keep you in sync with the dynamic developments of your content as well as close to the language of your users and their informational needs. If you’re going to do it…do it right.
Do you use controlled vocabularies for your technical writing projects? Share your personal experiences in the comments below.