The Three Core Topic Types

The Three Core Topic Types

• 1.
  The Three CoreTopic Types: Concept, Task, Reference © Marcia (Riefer Poulsen) Johnston 2006 [email_address]
• 2.
  To view inPowerPoint, press the F5 key (or in the menu bar go to Slide Show > View Show ), and click through the slides.
• 3.
  Thanks I’m gratefulfor 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 makingabout 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 Myexperience: Print = 20+ years Web = some Online Help = some My interest: Universal principles of topic-based writing
• 6.
  Why am Isharing what I’ve learned? Information typing has improved my writing. It might help yours too.
• 7.
  What we’ll coverWhat’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 atopic 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 intopics? 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 needthese. 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 createtopics with any tool. “ Modular writing is a cognitive process.” Kurt Ament, Single Sourcing: Building Modular Documentation Aka topic-based writing
• 14.
  What are thecore 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 topicsby 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’tlike 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 islinear, 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 makeup 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 getit. 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 awell-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 ofwell-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 onverb 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 atopic 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 totalk 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 somemakeovers. 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: Topicsthat 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: informationmodeling 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-basedwriting is not always easy to do. But the result is the easiest for people to use.
• 50.
  Books that discusstopic-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 BestPractices , a Publication of the Center for Information-Development Management (JoAnn Hackos, publisher and CIDM director) www.infomanagementcenter.com/newsletter.htm
• 52.
  Excellent article 10DITA 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 recordedwebinars on DITA https://xmetalevents.webex.com > View All Recorded Events Sponsored by XMetaL. List captured June 22, 2006.