WHATCHAMACALLITControlled Vocabularies for Technical Writers

Emilie BoillatInformation architectemilie.boillat@twygg.co

Write the Docs – Prague – 31 Aug. 2015

twygg.co

Username

Username

Twitter handle

Username

Twitter handle

Entity object

"user_mentions":[{"name":"Greg Babb", "indices":[23,31], "screen_name":"grbabb", "id":92488157, "id_str":"92488157"}]

● Understand information shared vocabulary →● Find information retrieval→● Capture information indexing→

CONTROLLED VOCABULARIES

CONTROLLED VOCABULARIES

Formality

Context

Free tags List of labels

Glossary

Thesaurus

Taxonomy

Ontology

1. LABELS

LABELS

LABELS – WHAT FOR

● Heterogeneous content ● Precision ● Disambiguation

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!

2. GLOSSARY

GLOSSARY

GLOSSARY – WHAT FOR

● Consistency ● Reference ● Context help

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!

3. BASIC THESAURUS

BASIC THESAURUS

= =

=

=

BASIC THESAURUS – WHAT FOR

● Increase set of results (search engine)

● Consistency (preferred term vs. variants)

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!

4. FULL-FLEDGED THESAURUS

FULL-FLEDGED THESAURUS

=

==

FULL THESAURUS – WHAT FOR

● Finding topics (hierarchy) ● Related topics (serendipity)● Overview of topics

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

5. TAXONOMY

TAXONOMY… is a ...

Apple

Fruit

Banana

TAXO

NO

MY

T

HES

AURU

S

Christmas tree

Tree

Apple tree Family tree

Apple tree

Tree

Palm tree

Apple

TAXONOMY – WHAT FOR

● Refine results of search or browsing (facets)

● Display related content (“See also...”)● Increase set of results (search engine)

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

CONCLUSION

NEED FOR CONTROLLED VOCABULARIES

Many small information units

Few large information units