Whatchamacallit: Controlled Vocabularies for Technical Writers (soap! 2015)
-
Upload
emilie-boillat -
Category
Software
-
view
636 -
download
2
Transcript of Whatchamacallit: Controlled Vocabularies for Technical Writers (soap! 2015)
WHATCHAMACALLIT
Controlled Vocabularies for Technical Writers
Emilie BoillatFounder, Twygghttp://twygg.co
SOAP Conference Krakow, 8th Oct. 2015
Username
Twitter handle
Entity object
"user_mentions":[{"name":"SoapConf", "indices":[34,42], "screen_name":"SoapConf", "id":1734634339, "id_str":"1734634339"}]
● Understand information shared vocabulary →● Find information retrieval→● Capture information indexing→
CONTROLLED VOCABULARIES
Formality
List of labels
Glossary
Full thesaurus
Taxonomy
Ontology
hi g
hCont ext
low
low
high
Basic thesaurus
Document
Free tags
Formality
List of labels
Glossary
Full thesaurus
Taxonomy
Ontology
hi g
hCont ext
low
low
high
Basic thesaurus
Document
Free tags
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!
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!
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!
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
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
Formality
List of labels
Glossary
Full thesaurus
Taxonomy
Ontology
hi g
hCont ext
low
low
high
Basic thesaurus
Document
Free tags
@eboillat
www.linkedin.com/pub/emilie-boillat/a/4b6/615
http://www.slideshare.net/EmilieBoillat
twygg.co
KEEP IN TOUCH