You can watch this talk here: https://www.youtube.com/watch?v=0kg-6YCDg64 An everyday dilemma in technical communication: What do you call that “thing”? Whether you ask developers, marketing folks or users, you often get very different views. Along with user interfaces, documentation helps all stakeholders align their mental model of a product. Terminology plays a key role, and a controlled vocabulary is an ace up the technical writer's sleeve. Controlled vocabularies are basically lists of concepts and the relationships between them. Beyond consistent naming, they are about structuring, categorizing and retrieving content. For example, you can use a vocabulary as a basis for documentation plans, tables of content, a help site's navigation, search filters, or even to organize test cases. In this talk, I share ways to create and maintain various types of vocabularies, and explain what each type is useful for. You can start with a flat list of terms and expand it into a glossary, a thesaurus, a taxonomy, or even a full-fledge ontology.

1. WHATCHAMACALLIT
Controlled Vocabularies for Technical Writers
Emilie Boillat
Information architect
emilie.boillat@twygg.co
Write the Docs – Prague – 31 Aug. 2015
twygg.co

4. Username

5. Username
Twitter handle

6. Username
Twitter handle
Entity object
"user_mentions":[{
"name":"Greg Babb",
"indices":[23,31],
"screen_name":"grbabb",
"id":92488157,
"id_str":"92488157"
}]

7. ● Understand information shared vocabulary→
● Find information retrieval→
● Capture information indexing→
CONTROLLED VOCABULARIES

8. CONTROLLED VOCABULARIES
Formality
Context
Free tags List of labels
Glossary
Thesaurus
Taxonomy
Ontology

9. 1. LABELS

12. LABELS

15. LABELS – WHAT FOR
● Heterogeneous content
● Precision
● Disambiguation

17. LABELS – HOW TO
● Tools: Paper cards, text editor, spreadsheet, …
● Sources:
– User interface analysis
– Lists of features (user stories, specifications, test cases, architecture
diagram,…)
– Site search analytics and tags
– Content analysis
– Existing vocabularies (glossaries, industry standards, competitors,
…)
● Tip: Consistent grammar and spelling!

19. 2. GLOSSARY

21. GLOSSARY

22. GLOSSARY – WHAT FOR
● Consistency
● Reference
● Context help

25. GLOSSARY – HOW TO
● Tools: Text editor, spreadsheet, wiki, …
● Sources:
– Existing documentation (concept topics), training materials,
marketing materials, specifications
– Interviews with subject-matter experts
– ev. Screenshots
● Tip: Make it easy to reach!

26. 3. BASIC THESAURUS

28. BASIC THESAURUS
= =
=
=

30. BASIC THESAURUS – WHAT FOR
● Increase set of results (search
engine)
● Consistency (preferred term vs.
variants)

31. BASIC THESAURUS – HOW TO
●
Tools: paper cards, spreadsheet, database, …
●
Sources:
– Interviews with users, product owners, developers, salespeople, ...
– Existing thesauri and dictionaries
●
Tips:
– Disambiguate or face semantic meltdown!
e.g. “Client (person)” = “Customer” ≠ “Client (computer)”
– Semantic equivalency depends on context of use!

33. 4. FULL-FLEDGED THESAURUS

36. FULL-FLEDGED THESAURUS
=
=
=

39. FULL THESAURUS – WHAT FOR
● Finding topics (hierarchy)
● Related topics (serendipity)
● Overview of topics

44. FULL THESAURUS – HOW TO
● Tools: Spreadsheet (no polyhierarchy), subject cards
(database or thesaurus management software), SKOS (W3C
standard)
● Sources:
– Card sorting exercise with users
– Hierarchy: Generic-specific, whole-part, class-instance (top-
down / bottom-up)
● Tips:
– Polyhierarchies (> 1 broader term) difficult to represent in a
navigation
– Use standards to guarantee compatibility across tools

46. 5. TAXONOMY

48. TAXONOMY
… is a ...

49. Apple
Fruit
Banana
TAXONOMYTHESAURUS
Christmas tree
Tree
Apple tree Family tree
Apple tree
Tree
Palm tree
Apple

50. TAXONOMY – WHAT FOR
● Refine results of search or browsing
(facets)
● Display related content (“See also...”)
● Increase set of results (search engine)

54. TAXONOMY – HOW TO
● Tools: Database, specialized taxonomy management
tool, spreadsheet (1 sheet/facet)
● Content analysis:
– What are the kind of properties shared by a lot of the
content? ( facets)→
– For each property, what are its sub-classes or instances?
● Tip: Get help from a data modelling expert

56. CONCLUSION

57. NEED FOR CONTROLLED
VOCABULARIES
Many small
information units
Few large
information units