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

2.
Username

3.
Username
Twitter handle

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

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

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

7.
1. LABELS

8.
LABELS

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

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

11.
2. GLOSSARY

12.
GLOSSARY

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

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

15.
3. BASIC THESAURUS

16.
BASIC THESAURUS
= =
=
=

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

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

19.
4. FULL-FLEDGED THESAURUS

20.
FULL-FLEDGED THESAURUS
=
=
=

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

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

23.
5. TAXONOMY

24.
TAXONOMY
… is a ...

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

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

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

28.
CONCLUSION

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