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.

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.