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

Username

Twitter handle

Username

Twitter handle

Entity object

"user_mentions":[{"name":"SoapConf", "indices":[34,42], "screen_name":"SoapConf", "id":1734634339, "id_str":"1734634339"}]

0. CONTROLLED VOCABULARIES

● 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

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 ● Embedded 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

Formality

List of labels

Glossary

Full thesaurus

Taxonomy

Ontology

hi g

hCont ext

low

low

high

Basic thesaurus

Document

Free tags

NEED FOR CONTROLLED VOCABULARIES

Many small information units

Few large information units

[email protected]

@eboillat

www.linkedin.com/pub/emilie-boillat/a/4b6/615

http://www.slideshare.net/EmilieBoillat

twygg.co

KEEP IN TOUCH