Introduction to Topic-Based Writing

1. Introduction to Topic-Based Writing NCR Information Engineering

2. About this presentation Purpose: • To provide an introduction to topic-based writing • What it is • How we will use it • How we will do it • The tools that make it possible • Requirements • To help writers get comfortable with this new approach Topic-Based Writing

3. About this presentation Intended Audience: • NCR Information Engineers • Other content creators • Users of Author-it Topic-Based Writing

4. About this presentation • Assumptions about you: • Familiar with technical writing • Motivated to improve technical content • Interested in learning about topic-based writing Topic-Based Writing

5. What is Topic-Based Writing? An Introduction to Topic-Based Writing

6. Before topic-based writing… • Technical writers created books • The term “book” implies paper-based manuals, which was the most common format • Page count measured the quality (instead of simply quantity) of technical content • Technical writers were encouraged to document everything • This approach contributes to increasingly thick manuals Topic-Based Writing

7. Background • Topic-based writing is a somewhat new approach to structuring information • Its roots are in the concept of “minimalism” (John Carroll) • It gained popularity when online help systems emerged in the mid 1990s • Built on the ideas that readers: • want to reach their goal quickly and successfully • do not read information for pleasure’s sake when accessing instructions • are slowed down and distracted by extraneous information Topic-Based Writing

8. Background • Instead of writing in book form, topics are self-contained, stand-alone bits of information • Think of topics as “doc-lets” • Book form • Topics are saved in flat files • Topic form • Topics are saved as records in a database Topic-Based Writing

9. Topic-Based Authoring Multiple authors per information product Book-Based Authoring One author per book A comparison Topic-Based Writing

10. Topic-Based Authoring Multiple authors per information product Topics serve multiple products and audiences Book-Based Authoring One author per book Books serve a single product and audience A comparison Topic-Based Writing

11. Topic-Based Authoring Multiple authors per information product Topics serve multiple products and audiences Content development is iterative Book-Based Authoring One author per book Books serve a single product and audience Content development is linear A comparison Topic-Based Writing

12. Topic-Based Authoring Multiple authors per information product Topics serve multiple products and audiences Content development is iterative Presentation layout can be template-driven Book-Based Authoring One author per book Books serve a single product and audience Content development is linear Presentation layout requires manual work A comparison Topic-Based Writing

13. Topic-Based Authoring Multiple authors per information product Topics serve multiple products and audiences Content development is iterative Presentation layout can be template-driven Well suited for modular hardware/software products with short lifecycle or long life span Book-Based Authoring One author per book Books serve a single product and audience Content development is linear Presentation layout requires manual work Well suited for highly technical or one-of-a-kind products with a long development cycle and/or short life span A comparison Topic-Based Writing

14. Characteristics of topic-based writing • Information is chunked • Solid technical writing already emphasizes and uses this approach • Uses consistent writing style and phrasing • Reliance on the style guide is critical • Many contributors to each information product, but the reader can’t tell • The singular voice Topic-Based Writing

15. Characteristics of topic-based writing …cont’d • Topics can be pulled together in any combination, to meet the needs of different users • Different output forms (web, online help, print) • Different audiences (internal vs. external, or beginner, novice, advanced) • Authors create content without anticipating how it will be used • This enables reusable content! Topic-Based Writing

16. Benefits of topic-based writing to IE • SMEs can review topics as soon as they are written • Do not have to wait for completion of book • This fits more closely with Agile software development methodologies • Consistently structured topics: • Help users navigate content • Make it easy to reuse content in multiple deliverables Topic-Based Writing

17. Terms you’ll also hear • Structured authoring • definition • Modular writing • Single sourcing • Maintaining a single, definitive source of content. Reuse is merely a benefit of single-sourcing. • Content reuse/Reusable Content • A piece of information that is unconstrained, and not tied to one deliverable type Topic-Based Writing

18. Terms you’ll also hear… cont’d • DITA (Darwin Information Typing Architecture) • A standard for defining online help and support information in XML using a DTD schema that covers "topic," "concept," "task" and "reference" categories. • Minimalism • An approach to information development using task-based chunks of information • Information typing • Separating content into easily identifiable chunks of information Topic-Based Writing

19. Topic-based writing motto • Write it once, review it once, use it over and over again Use Review Write Topic Topic Topic Topic Topic Topic Topic Topic Topic Topic Topic Topic-Based Writing

20. Reusable content Parameters Technical Whitepapers Release Bulletin Info Topics in the database Technical Knowledge Base Articles Training Content Web Content ??? Tech Publications 2014-11-16 Topic-Based Writing NCR Confidential 20

21. Topic-Based Writing in the Real World An Introduction to Topic-Based Writing

22. Why should I care about topic-based writing? • Many industry-leading companies are moving to topic-based writing for their technical documentation • Using the latest technology and methods presents a career growth opportunity • This method has the potential to ease the workforce shortages we face • You can concentrate more on the content, not how it looks when published • You get to collaborate more closely with your colleagues Topic-Based Writing

23. How does topic-based writing relate to Author-it? • Topic-based writing is a METHOD or APPROACH • Author-it is simply a TOOL that helps put the method into place • Author-it is a content management system (CMS) • It contains a SQL database • Each topic is a record in the SQL database • Because topics are stand alone units, you can reuse them in multiple ways Topic-Based Writing

24. Here’s a look at Author-it Topic-Based Writing

25. And here are some topics Topic-Based Writing

26. And here are some topics in a “book object” Topic-Based Writing

27. How does it affect my day-to-day job? • Less focus on formatting • More focus on content • More collaboration between writers • Decreased focus on ownership of books • Increased need to adhere to the Style Guide • New tool to learn • Different process for publishing and archiving • More chance to reuse existing content • Increased ability to create multiple output formats with a minimal amount of work Topic-Based Writing

28. Publishing and Archiving Changes • Publishing: • Author-it includes release state flags that you must apply to each topic as it matures through the development cycle towards publication: Topic-Based Writing

29. What are Topics? An Introduction to Topic-Based Writing

30. Let’s discuss topics… According to JoAnn Hackos, each topic: • has a title to name its purpose • contains enough content for someone to begin and complete a task, grasp a basic concept, or look up critical reference information • has a carefully defined set of the basic content units that are required and accommodates other optional content Topic-Based Writing

31. What is a topic? An information chunk that: • answers one question • How do I…? • What is...? • What went wrong…? • has a heading • can stand alone — makes sense in any context • points to related topics (if appropriate) Topic-Based Writing

32. How does a topic stand alone? Topics = Building Blocks • make sense on their own (are context-free) • can be assembled in different ways • avoid transitions at beginning or end (“see the following table”, etc.) • are easy to read and comprehend (always spell out acronyms or use a pop-up definition) Topic-Based Writing

33. How does a topic stand alone … cont’d Topics = Building Blocks • are format-free (use tagging to identify elements such as heading, body, bullet-list item, numbered-list item) • use standard phrasing that conforms to the Style Guide (“To install the widget:”; “For more information, see…”) Topic-Based Writing

34. How long should a topic be? • As long as it needs to be to answer one question • (Does not have to fit on a single screen – scrolling is allowed.) Topic 1 Topic 2 About the WidgetThis paragraph is all it takes to describe the widget. So, this topic is short. Installing the WidgetThis topic is longer because of all the steps required. 1. Do this. 2. Do that. 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 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 Topic-Based Writing

35. How long should a topic be … cont’d • As short as it can be while still making sense all on its own • Includes all the information it needs to be understood without additional context • Is not cluttered with extra information that may apply to one context but not another Topic 2 Topic 1 Cleaning the Widget in Zero GravityWhatever you do, don’t use a liquid solvent. Use antiseptic wipes only. 1. Do this… Cleaning the WidgetPut the entire widget-cleaning procedure here, unless it varies according to context. Then you need more than one topic. Installing the WidgetThis topic is longer because of all the steps required. 1. Do this. 2. Do that. Topic-Based Writing

36. Why write in topics? Benefits to Users: • fits the non-sequential way they use technical information • lets them get right to the information they need, without having to read a bunch of stuff they don’t need • gathers information into neat little packages that answer one question completely and succinctly • helps them get their jobs done by supporting task-centric (vs. product-centric) documentation • the information products they get can be customized to suit their information needs Topic-Based Writing

37. Why write in topics? Benefits To Writers: • supports multi-writer collaboration • enables information reuse (single-sourcing) • makes it easier for us to create information products to support large solutions including more than one product • some stuff from Passport, some stuff from TM, some stuff from WiseIP… • reduces redundancy • information exists in only one place, so updated only once Topic-Based Writing

38. Don’t I already write in topics? • Maybe… • Many seasoned technical writers already think about and structure content in bite-sized chunks • But… • working with FrameMaker (and Word to a lesser extent) necessarily means that you think of content in book-based format • And… • this workshop is meant to ensure that all NCR authors share a common understanding of topic-based writing Topic-Based Writing

39. The Three Topic Types An Introduction to Topic-Based Writing

40. The three topic types Describes something. Tells how to do something. Usually includes numbered steps. Gives details of interest about something to certain readers, often in list or table form. Concept Task Reference Topic-Based Writing

41. Here’s another way to look at the three topic types Concept Learning Task Doing Reference Knowing Topic-Based Writing

42. 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 about something Concept Task Reference Topic-Based Writing

43. The Three Topic Types in Action An Introduction to Topic-Based Writing

44. Examples • In this series of slides, you will see examples of the three topic types at work Concept Task Reference Topic-Based Writing

45. Concept About conference calls Use a conference call to speak with more than two people in two different locations at the same time. Use one of the following types of conference calls to speak with multiple people. Three-way conference calls Three-way conference calling connects two other people to a call. Multi-line conference calls Multi-line conference calling connects you to more than two but fewer than eight other people on a call. Dial-in conference calls Dial-in conference calling uses a single conference call number to connect multiple people. Topic-Based Writing

46. Concept • ImageMark Passport is a remote capture solution for capturing check and image transactions at any of the following remote locations: • the branch • an ATM • a commercial client • Passport capture then transmits the images and data to a central point where they are consolidated into larger units of work and passed on for further processing. • Passport can also work as a front-end capture solution for an image-POD system, such as ImageMark Transaction Manager or ImageMark NCompass. Topic-Based Writing

47. Task Replacing the Inkjet Cartridge When the endorsement print becomes light and difficult to read, replace the ink jet cartridge. When changing the ink jet cartridge, follow these steps: • Turn off the power. • Open the cover. • Remove the ink-jet cartridge by pulling it up and out of its holder. • Discard the used cartridge. • Take the new cartridge out of its packaging and remove the protective tape. • Place the front of the cartridge down and into its holder. • Push down on the rear tab until it snaps into place. Topic-Based Writing

48. Task Checking System Messages Check for system messages in case problems arose from the previous work cycle. To check system messages: • In Task Manager, choose Diagnostics from the Utilities list. The system displays the Diagnostics window. • Acknowledge all outstanding messages and take the suggested corrective action. For more information on handling error messages, see Troubleshooting. • Minimize Diagnostics. If error messages are received during the day, this icon will flash and beep to alert you. • Return to Application Manager. • Keep the Application Manager window open throughout the day to monitor and manage workflow. For more information, see Application Manager. Topic-Based Writing

49. Reference Hazardous Waste Drop-Off You may drop off hazardous waste free of charge at your local landfill on the first Saturday of each month. The following items are accepted: • Paint • Cleaning solvents • Non-functional electronics • Batteries • Deceased pets Topic-Based Writing

50. Reference ImageMark Parameter Files – ASCII and Related Support Files Topic-Based Writing