10 mistakes companies make when moving to topic-based authoring
Sharon BurtonE-mail: Sharon@sharonburton.comTweet: Sharonburton Photo by Rachel Houghton
I’m Sharon Burton ▪ Content Strategy consultant Been in the Tech Comm industry for nearly 20 years STC Associate Fellow Teach: ▪ Technical Communication to Engineering students at the University of California, Riverside ▪ Tech Comm certificate program at UCR Extension ▪ STC Certificate Courses ▪ University of Redlands I knit, crochet, design patterns, write, garden, have a large dog, and am all around just fun
Topic-based authoring is a modular content creation approach (popular in the technical publications and documentation arenas) that supports XML content reuse, content management, and makes the dynamic assembly of personalized information possible. A topic is a discrete piece of content that is about a specific subject, has an identifiable purpose, and can stand alone (does not need to be presented in context for the end-user to make sense of the content). Topics are also reusable. They can, when constructed properly (without reliance on other content for its meaning), be reused in any context anywhere needed. The Darwin Information Typing Architecture (DITA) is a standard designed to help authors create topic-based content. The standard is managed by the Organization for the Advancement of Structured Information Standards (OASIS) DITA Technical Committee. From Wikipedia
Focuses effort on the information your user needs to use the product Develop a body of information that’s helpful to the user Maximize content reuse Roughly similar to structuring an online help system People who’ve developed a lot of help “get” these concepts faster If you are moving to DITA, it’s part of the trip But you don’t have to move to DITA to make use of this information development method This can be a destination as well as a rest stop
Topics are small, perhaps ½ to 4 printed pages Perhaps smaller Only include the information needed to Perform one procedure Understand one concept Topics can be (re)combined New products, deliverables, or other ways Topics are easier to update Easier and cheaper to get approval for updating topics from management Depending on deliverables, push updated topics to your users
Library Adding About Programming Users Objects and Relating Inheritance Objects ImportingPlacing SettingObjects Reports Permissions Containing Editing Objects Reports Deleting Printing Setting Reports Schedules Users About About Objects Reports Using Container About Objects Schedules About Users Customizing Objects Saving Creating reports Reports Exporting Objects About Containment
Library Admin Guide Programmers Guide Getting Started• About Users • About • About Users • Adding Users Programming • About Reports • Deleting Users • About Objects • About • Setting • Placing Objects Programming Permissions • About • About Objects• About Reports Containment • About • Creating Reports • Objects and Containment • Editing Reports Inheritance • Exporting Objects • Saving Reports • Using Container • About Schedules Objects • Printing Reports • Customizing • Importing Reports Objects • Relating Objects
Management and other teams need to understand why this is better This is not going to see an instant and dramatic improvement Except localization Costs may drop immediately Schedules may be impacted Less content can be scary
The tools that got you into this mess are probably not the tools to get you out Asking Techwr-l what they use and buying that not the answer Doesn’t hurt to ask Evaluate what your needs are now and in the future Work with the vendors closely to make sure what you need is what they can do
The processes for developing, editing, and publishing a 200 page manual won’t work Developing Topic-based content is different Topics “stand alone” on content and/or formatting Topics are reviewed as they are ready Review process must change Maybe use a special review product
New tools + new process = training Not training sets projects and people up for failure Training provides more than how to use the product Includes best practices for our workflow Identifies the changes for our workflow Instantiates how we do what we do
Your legacy content is not going to fit neatly It’s at least not well written/structured/organized You can’t jump on your horse and ride off in all directions You need to analyze what you have before you can decide what you have One manual may not give you the real picture Especially if you had a lot of contractors, the legacy content has been around a long time, and so on This can be very hard People want their content to be the exception It’s special content, not like other content and needs special attention
Before we can start thinking about moving to topic-based authoring And gaining the benefits thereof We must have good writing standards in place Content reuse demands consistent writing standards The content can appear in many places In more than one deliverable You may need to localize so why not prepare now?
Because most tools allow you to import and slice your legacy content based on headings, it can feel like you’re done when you import That’s step #1 of x and x is bigger than 2 Now you need to think about Content reuse Smaller topics Embedded topics (snippets) Localization?
Rewriting existing content is expensive You can’t reuse what you can’t find Opportunistic reuse People remember this content from before Maybe they can find it Big time sink Systematic reuse The system knows this content has been written previously Prompts the writer for reuse Tracks reuse and reports it
Develop information based on the users’ information needs The next logical step in Minimalism Matches the Use Case or Scenario dev environment Minimalism is not writing as little as possible It’s developing the information your users actually need NOT how the database is structured How to run a report and print it
Your legacy content is going to fit neatly in content categories It won’t take any time to figure this out We can do this as we need to It’s easy We’ll hire an intern to do it We can meet deadlines while we completely restructure all our content
Single Sourcing: Building Modular Documentation by Kurt Ament ISBN-10: 0815514913 or ISBN-13: 978-0815514916 Information Development: Managing Your Documentation Projects, Portfolio, and People by JoAnn T. Hackos ISBN-10: 0471777110 or ISBN-13: 978-0471777113 User and Task Analysis for Interface Design by JoAnn T., PhD Hackos and Janice C. Redish ISBN-10: 0471178314 or ISBN-13: 978-0471178316
Wait a Minute, I Have to Take Off My Bra, 2011. ISBN-10: 0981333516. Anthology of creative non-fiction and poetry My first creative non-fiction book publication You should by it! Available on Amazon. Click here.