Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Whatchamacallit: Controlled Vocabularies for Technical Writers (soap! 2015)

793 views

Published on

Note: Go to the last slide for a video of the same talk at Write the Docs Europe 2015 (https://www.youtube.com/watch?v=0kg-6YCDg64).

An everyday dilemma in technical communication: What do you call that “thing”? Whether you ask developers, marketing folks or users, you often get very different views.

Along with user interfaces, documentation helps all stakeholders align their mental model of a product. Terminology plays a key role, and a controlled vocabulary is an ace up the technical writer’s sleeve.
Controlled vocabularies are basically lists of concepts and the relationships between them. Beyond consistent naming, they are about structuring, categorizing and retrieving content. For example, you can use a vocabulary as a basis for documentation plans, tables of content, a help site’s navigation, search filters, or even to organize test cases.
In this talk, I will share ways to create and maintain various types of vocabularies, and explain what each type is useful for. You can start with a flat list of terms and expand it into a glossary, a thesaurus, a taxonomy, or even a full-fledged ontology.

Published in: Software
  • Be the first to comment

  • Be the first to like this

Whatchamacallit: Controlled Vocabularies for Technical Writers (soap! 2015)

  1. 1. WHATCHAMACALLIT Controlled Vocabularies for Technical Writers Emilie Boillat Founder, Twygg http://twygg.co SOAP Conference Krakow, 8th Oct. 2015
  2. 2. Username
  3. 3. Username Twitter handle
  4. 4. Username Twitter handle Entity object "user_mentions":[{ "name":"SoapConf", "indices":[34,42], "screen_name":"SoapConf", "id":1734634339, "id_str":"1734634339" }]
  5. 5. 0. CONTROLLED VOCABULARIES
  6. 6. ● Understand information shared vocabulary→ ● Find information retrieval→ ● Capture information indexing→ CONTROLLED VOCABULARIES
  7. 7. Formality List of labels Glossary Full thesaurus Taxonomy Ontology high Context low low high Basic thesaurus Document Free tags
  8. 8. Formality List of labels Glossary Full thesaurus Taxonomy Ontology high Context low low high Basic thesaurus Document Free tags
  9. 9. 1. LABELS
  10. 10. LABELS
  11. 11. LABELS – WHAT FOR ● Heterogeneous content ● Precision ● Disambiguation
  12. 12. 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!
  13. 13. 2. GLOSSARY
  14. 14. GLOSSARY
  15. 15. GLOSSARY – WHAT FOR ● Consistency ● Reference ● Embedded help
  16. 16. 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!
  17. 17. 3. BASIC THESAURUS
  18. 18. BASIC THESAURUS = = = =
  19. 19. BASIC THESAURUS – WHAT FOR ● Increase set of results (search engine) ● Consistency (preferred term vs. variants)
  20. 20. 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!
  21. 21. 4. FULL-FLEDGED THESAURUS
  22. 22. FULL-FLEDGED THESAURUS = = =
  23. 23. FULL THESAURUS – WHAT FOR ● Finding topics (hierarchy) ● Related topics (serendipity) ● Overview of topics
  24. 24. 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
  25. 25. 5. TAXONOMY
  26. 26. TAXONOMY … is a ...
  27. 27. Apple Fruit Banana TAXONOMYTHESAURUS Christmas tree Tree Apple tree Family tree Apple tree Tree Palm tree Apple
  28. 28. TAXONOMY – WHAT FOR ● Refine results of search or browsing (facets) ● Display related content (“See also...”) ● Increase set of results (search engine)
  29. 29. 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
  30. 30. CONCLUSION
  31. 31. Formality List of labels Glossary Full thesaurus Taxonomy Ontology high Context low low high Basic thesaurus Document Free tags
  32. 32. NEED FOR CONTROLLED VOCABULARIES Many small information units Few large information units
  33. 33. emilie.boillat@twygg.co @eboillat www.linkedin.com/pub/emilie-boillat/a/4b6/615 http://www.slideshare.net/EmilieBoillat twygg.co KEEP IN TOUCH

×