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 (Write the Docs 2015)

794 views

Published on

You can watch this talk here: 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 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-fledge ontology.

Published in: Software
  • Be the first to comment

Whatchamacallit: Controlled Vocabularies for Technical Writers (Write the Docs 2015)

  1. 1. WHATCHAMACALLIT Controlled Vocabularies for Technical Writers Emilie Boillat Information architect emilie.boillat@twygg.co Write the Docs – Prague – 31 Aug. 2015 twygg.co
  2. 2. Username
  3. 3. Username Twitter handle
  4. 4. Username Twitter handle Entity object "user_mentions":[{ "name":"Greg Babb", "indices":[23,31], "screen_name":"grbabb", "id":92488157, "id_str":"92488157" }]
  5. 5. ● Understand information shared vocabulary→ ● Find information retrieval→ ● Capture information indexing→ CONTROLLED VOCABULARIES
  6. 6. CONTROLLED VOCABULARIES Formality Context Free tags List of labels Glossary Thesaurus Taxonomy Ontology
  7. 7. 1. LABELS
  8. 8. LABELS
  9. 9. LABELS – WHAT FOR ● Heterogeneous content ● Precision ● Disambiguation
  10. 10. 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!
  11. 11. 2. GLOSSARY
  12. 12. GLOSSARY
  13. 13. GLOSSARY – WHAT FOR ● Consistency ● Reference ● Context help
  14. 14. 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!
  15. 15. 3. BASIC THESAURUS
  16. 16. BASIC THESAURUS = = = =
  17. 17. BASIC THESAURUS – WHAT FOR ● Increase set of results (search engine) ● Consistency (preferred term vs. variants)
  18. 18. 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!
  19. 19. 4. FULL-FLEDGED THESAURUS
  20. 20. FULL-FLEDGED THESAURUS = = =
  21. 21. FULL THESAURUS – WHAT FOR ● Finding topics (hierarchy) ● Related topics (serendipity) ● Overview of topics
  22. 22. 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
  23. 23. 5. TAXONOMY
  24. 24. TAXONOMY … is a ...
  25. 25. Apple Fruit Banana TAXONOMYTHESAURUS Christmas tree Tree Apple tree Family tree Apple tree Tree Palm tree Apple
  26. 26. TAXONOMY – WHAT FOR ● Refine results of search or browsing (facets) ● Display related content (“See also...”) ● Increase set of results (search engine)
  27. 27. 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
  28. 28. CONCLUSION
  29. 29. NEED FOR CONTROLLED VOCABULARIES Many small information units Few large information units

×