The Three Core Topic Types
Download as PPS, PPTX3 likes4,527 views
The document discusses the three core topic types of concept, task, and reference for organizing information. It describes the characteristics of well-formed topics, including using heading syntax to indicate topic type, focusing on one question, and linking to related topics. The document provides examples of restructuring topics to better fit the core types and improve usability.
![The Three Core Topic Types: Concept, Task, Reference © Marcia (Riefer Poulsen) Johnston 2006 [email_address]](https://image.slidesharecdn.com/threetopictypes-12806341712272-phpapp01/85/The-Three-Core-Topic-Types-1-320.jpg)
![Another way to talk about hubs “ To help users navigate modular content, you link standalone content modules with cognitive bridges , or cross-references . . . . When separating different levels of information into distinct content modules, [you] physically separate modules that are thematically related. To make the relationships between the related modules explicit, you add cross-references that link the modules .” Kurt Ament, Single Sourcing: Building Modular Documentation](https://image.slidesharecdn.com/threetopictypes-12806341712272-phpapp01/85/The-Three-Core-Topic-Types-40-320.jpg)
More Related Content
Similar to The Three Core Topic Types (20)
The Three Core Topic Types
- 1. The Three Core Topic Types: Concept, Task, Reference © Marcia (Riefer Poulsen) Johnston 2006 [email_address]
- 2. To view in PowerPoint, press the F5 key (or in the menu bar go to Slide Show > View Show ), and click through the slides.
- 3. Thanks I’m grateful for feedback on this presentation from STC’s single sourcing & online SIGs STC’s Rochester & Central New York chapters Tech Comm colleagues at Welch Allyn, Inc.
- 4. Assumptions I’m making about you Experienced tech communicator Think in terms of information chunks Don’t (yet) think in terms of these three topic types — or want to refine your topic-writing skills
- 5. About me My experience: Print = 20+ years Web = some Online Help = some My interest: Universal principles of topic-based writing
- 6. Why am I sharing what I’ve learned? Information typing has improved my writing. It might help yours too.
- 7. What we’ll cover What’s a topic? Why write in topics? What tools do we need to create topics? What are these 3 core topic types? Why 3, and why are they core types? Why organize topics by info type? What elements make up topics? What might each topic type look like? What’s the process for topic-based writing? What makes a well-formed topic?
- 8. At the end, you’ll make this over. Isn’t this already in chunks?
- 9. What’s a topic? Information chunk that answers one question (How do I…? What is...? etc.) has a heading can stand alone — makes sense in any context Hey, this slide is an example of a topic.
- 10. How does a topic stand alone? Art borrowed from an ArcSoft PhotoMontage ad Topics = building blocks Make sense on their own Can be assembled different ways Avoid transitions at beg. or end (“As you’ve just seen,” etc.) Do We Really Need All that Glue? JoAnn Hackos on transitional text in topics http://dita.xml.org/node/1410
- 11. Why write in topics? Topic-based writing fits the way people seek technical info supports task-centric (vs. product-centric) documentation supports multiwriter collaboration enables information reuse (single sourcing) streamlines translation
- 12. You don’t need these. DITA or DocBook, DTDs or schemas XML, HTML, or any other ML Structured FrameMaker A content-management system A particular tool or standard A particular output type (print, Web, Help)
- 13. You can create topics with any tool. “ Modular writing is a cognitive process.” Kurt Ament, Single Sourcing: Building Modular Documentation Aka topic-based writing
- 14. What are the core topic types? Tells how to do something. Usually includes numbered steps. Task Concept Reference Gives details of interest to certain readers, often in look-up lists or tables. Describes something.
- 15. Why three types (at least as a starting point)? The concept-task-reference triptych has been in use for years, although not embraced by everyone. The growing use of DITA, which offers these three types “out of the box,” reinforces the consensus. For more: http://stc-on.org/online/topics/content-management/2006/08/19/topic-types/
- 16. Why call them core types? Could say core types, super-types, archetypes, or ur types. These types are universally relevant and customizable . In DITA, you customize via specialization and inheritance .
- 17. What is DITA? DITA = Darwin Information Typing Architecture Topic-based XML framework for authoring, managing, publishing technical documentation. Illustration reprinted with permission from artist, Rick Geary (www.rickgeary.com). Information typing is DITA’s middle name.
- 18. Why structure topics by info type? So readers instantly know a topic’s purpose: to help them understand something to help them do something to provide supporting details Task Concept Reference
- 19. True or False? “Online information should be presented in screen-sized chunks. People don’t like to scroll down.” “Hardcopy info is linear, online info is nonlinear.” Let’s look at each of these fallacies.
- 20. Fallacy: People don’t like to scroll down. How long should a topic be? Long enough to address the question (How do I…? What is...? etc.). This topic is longer becausy of all the steps required to This topic is longer becaush of all the steps required to This topic is longer becausm of all the steps required to About Widgets This paragraph is all it takes to describe the widget. So, this topic is short. Topic 1 This topic is longer because of all the steps required to This topic is longer becausc of all the steps required to This topic is longer becaust of all the steps required to Installing a Widget This topic is longer because of all the steps required. 1. Do this. 2. Do that. Topic 2
- 21. Fallacy: Hardcopy is linear, online is nonlinear. What’s the reality? In any medium , people sometimes read technical info sequentially and sometimes jump around. Can’t assume sequential reading in a chapter. Write for sequential reading in a topic. Topic C Topic X Topic M Chap 5 Chap 8 Chap 2
- 22. What elements make up topics? From Introduction to DITA: A User Guide to the Darwin Information Typing Architecture Elements Topics Depends on your needs. Here’s one example: Mini building blocks
- 23. Concept topic — example 1 From The Internet for Dummies, 2 nd edition Elements Topic
- 24. Concept topics — example 2 Can be read in any order. From Boys’ Life, July 2006 Topic Topic Topic Topic Topic Topic Topic
- 25. Task topic — example 1 Elements Topic From Polaris ® PowerPAC online help
- 26. Task topic — example 2 Setting Categories Elements Topic From FranklinCovey ® planning software online help
- 27. Reference topic — example 1 Elements Topic From The Internet for Dummies, 2 nd edition Sidebar adjacent to other topics
- 28. Reference topic — example 2 Table tucked away in an appendix Topic Elements
- 29. Okay. I get it. How do I do it? Identify the task topics needed — based on user goals, not user interface. (“Resetting the Trip Timer” vs. “DST Mode”) Identify the concept and reference topics needed to support those tasks. (“About the Trip Timer” or “Specifications”) Create, assemble, and publish the topics. (≈ TOCs, playlists) I. Topic area a. Concept topic b. Task topic II. Topic area Might look like an old-fashioned outline.
- 30. What makes a well-formed topic? The rest of presentation addresses this question. My focus: Common characteristics of all topic types. Beyond my focus: Specifics on well-formed procedures, descriptions, tables, etc. (widely documented).
- 31. 4 characteristics of well-formed topics They use heading syntax to communicate info type. They avoid significant mixing of info types. They serve as a hub, pointing to related topics (if appropriate). They focus on one user question. Let’s look at each of these.
- 32. Well-formed topic — characteristic 1 A well-formed topic uses heading syntax to communicate info type.
- 33. Heading syntax — examples Concept headings 1 st word = noun, About, question word Task headings 1 st word = gerund, infinitive, imperative, How To, question word Reference headings 1 st word = noun, question word Setting Up the XYZ To Set Up the XYZ Set Up the XYZ How To Set Up the XYZ How Do I Set Up the XYZ? XYZ or About XYZ What Is XYZ? Specifications Do You Need a Number to Get a Name?
- 34. For more on verb forms in topic titles See STC’s Hyperviews Online: http://stc-on.org/online/topics/content-management/2006/08/15/topic-titles-what-verb-form/
- 35. Well-formed topic — characteristic 2 A well-formed topic avoids significant mixing of info types (beyond a few sentences). Concept with procedure embedded Task with lengthy background embedded Reference table with concepts embedded
- 36. Mixed info types — example This descriptive interruption goes on for another page before we reach step 6! Concept info embedded in task. Might want to keep bits of it here.
- 37. Well-formed topic — characteristic 3 A well-formed topic serves as a “ hub .” Term used by JoAnn Hackos, quoting Eric Freese, in Content Management for Dynamic Web Delivery
- 38. How does a topic serve as a hub? It’s like a gate at an airport. It becomes the center of your field of vision when you land there. It directs you to where you want to go next. It doesn’t have to convey the layout of the whole airport. How do we get from here to Gate D25? Hub
- 39. Topics as hubs — example Task ABC 1. Do this. 2. Do that. Related Information Concept PQR Reference XYZ Concept PQR This explanation tells all about PQR. Related Information Task ABC Reference XYZ Reference XYZ Item Description Blah Blah blah blah Blah Blah blah blah Related Information Task ABC Concept PQR Hub Hub Hub Kurt Ament calls such cross-references “cognitive bridges.” Keep “Related Info” lists short and highly relevant.
- 40. Another way to talk about hubs “ To help users navigate modular content, you link standalone content modules with cognitive bridges , or cross-references . . . . When separating different levels of information into distinct content modules, [you] physically separate modules that are thematically related. To make the relationships between the related modules explicit, you add cross-references that link the modules .” Kurt Ament, Single Sourcing: Building Modular Documentation
- 41. Well-formed topic — characteristic 4 A well-formed topic answers one user question . As fully as users need Only as fully as users need Minimalism
- 42. Let’s try some makeovers. Following are two before and after examples. I did not make these up.
- 43. Makeover #1 — before How well-formed is this topic? Does it use heading syntax to communicate info type? Does it avoid significant mixing of info types? Does it serve as a hub — point to related topics? Does it answer one user question (only as fully as needed)?
- 44. Makeover #1 — after If a lead-in grows, you might spin it off into its own concept topic.
- 45. Makeover #2 — before
- 46. Makeover #2 — after
- 47. Ideal: Topics that stand alone AND read well in “browse sequence” You can jump to these topics in any order AND scroll from one to the next.
- 48. Your challenge: information modeling Create an information model* for your context. What topic types best serve our customers? What elements will those topics typically contain? What syntax patterns will our headings follow? How else can we standardize for more consistent content structure? * term used by JoAnn Hackos and others
- 49. Child’s play? Topic-based writing is not always easy to do. But the result is the easiest for people to use.
- 50. Books that discuss topic-based writing Developing Quality Technical Information: A Handbook for Writers and Editors , 2 nd ed., IBM Press, Prentice Hall PTR, 2004. Standards for Online Communication , JoAnn Hackos & Dawn Stevens, John Wiley & Sons, 1997. Single Sourcing: Building Modular Documentation , Kurt Ament, William Andrew Publishing, 2003. Introduction to DITA: A User Guide to the Darwin Information Typing Architecture , Jennifer Linton & Kylene Bruski, Comtech Services, 2006 (written using DITA). Content Management for Dynamic Web Delivery , JoAnn Hackos, Wiley Computer Publishing, 2001.
- 51. Recommended newsletter Best Practices , a Publication of the Center for Information-Development Management (JoAnn Hackos, publisher and CIDM director) www.infomanagementcenter.com/newsletter.htm
- 52. Excellent article 10 DITA Lessons Learned From Tech Writers in the Trenches “ The main difficulty writers had was to make the switch to writing topic based material. ” http://thecontentwrangler.com/article/10_dita_lessons_learned/
- 53. Excellent free recorded webinars on DITA https://xmetalevents.webex.com > View All Recorded Events Sponsored by XMetaL. List captured June 22, 2006.
Editor's Notes
- #12: REUSE: Maximized if using CMS. Limited in Word, FrameMaker, etc. Example: Easy to reuse same chapter in different Frame books. Might reuse topics by importing them. Might reuse smaller elements using cross-references. Not ideal. TRANSLATION: (1) Can send topics for translation as they're approved vs. waiting for a whole document to be approved. Doesn't save costs, but reduces wait time. (2) Since topics make sense in any context, they can be reused without any tweaking in any language. (3) Easier to update translated text in standalone topics.
- #16: Thanks to Mark Baker in the Single Sourcing SIG, and to online Help expert Neil Perlin, for helpful discussions on these questions. Some customized topics that people have mentioned: planning methods facts processes principles troubleshooting Show-Me demos
- #17: JoAnn Hackos 9/8/06 response to a query posted by a single-sourcing SIG member : “ These components (methods, methodology, results, findings, conclusions, and recommendations) are standard parts of research reports everywhere. One of our clients, The Research Foundation of the American Waterworks Association, uses exactly the same format, as do most research organizations. It would be worthwhile to consider a DITA subcommittee on a research report specialization. Perhaps the specialization would not have to be structural , in that the generic topic might work well structurally. Remember that the generic topic is closest to the concept information type. However, it seems that research reports might require a domain specialization, which means developing specific semantics in the form of XML tags and possibly metadata categories that would assist in properly labeling content in the reports.”