Note: Go to the last slide for a video of the same talk at Write the Docs Europe 2015 (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 will 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-fledged ontology.

1. WHATCHAMACALLIT
Controlled Vocabularies for Technical Writers
Emilie Boillat
Founder, Twygg
http://twygg.co
SOAP Conference
Krakow, 8th
Oct. 2015

4. Username

5. Username
Twitter handle

6. Username
Twitter handle
Entity object
"user_mentions":[{
"name":"SoapConf",
"indices":[34,42],
"screen_name":"SoapConf",
"id":1734634339,
"id_str":"1734634339"
}]

7. 0. CONTROLLED VOCABULARIES

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

9. Formality
List of labels
Glossary
Full thesaurus
Taxonomy
Ontology
high
Context
low
low
high
Basic thesaurus
Document
Free tags

10. Formality
List of labels
Glossary
Full thesaurus
Taxonomy
Ontology
high
Context
low
low
high
Basic thesaurus
Document
Free tags

11. 1. LABELS

14. LABELS

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

18. 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!

21. 2. GLOSSARY

23. GLOSSARY

25. GLOSSARY – WHAT FOR
● Consistency
● Reference
● Embedded help

26. 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!

28. 3. BASIC THESAURUS

30. BASIC THESAURUS
= =
=
=

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

34. 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!

36. 4. FULL-FLEDGED THESAURUS

39. FULL-FLEDGED THESAURUS
=
=
=

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

46. 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

48. 5. TAXONOMY

50. TAXONOMY
… is a ...

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

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

57. 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

59. CONCLUSION

60. Formality
List of labels
Glossary
Full thesaurus
Taxonomy
Ontology
high
Context
low
low
high
Basic thesaurus
Document
Free tags

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

62. emilie.boillat@twygg.co
@eboillat
www.linkedin.com/pub/emilie-boillat/a/4b6/615
http://www.slideshare.net/EmilieBoillat
twygg.co
KEEP IN TOUCH