10 mistakes companies make when moving to topic-based authoring


Published on

Published in: Technology, Business
  • Be the first to comment

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

10 mistakes companies make when moving to topic-based authoring

  1. 1. Sharon BurtonE-mail: Sharon@sharonburton.comTweet: Sharonburton Photo by Rachel Houghton
  2. 2.  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
  3. 3. Quick definition
  4. 4.  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
  5. 5.  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
  6. 6.  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
  7. 7. 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
  8. 8. 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
  9. 9. How to mess this up
  10. 10.  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
  11. 11.  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
  12. 12.  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
  13. 13.  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
  14. 14.  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
  15. 15.  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?
  16. 16.  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?
  17. 17.  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
  18. 18.  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
  19. 19.  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
  20. 20.  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
  21. 21.  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.
  22. 22. Contact me: E-mail: Sharon@sharonburton.com Twitter: Sharonburton