Post on 16-Apr-2017
transcript
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