10 mistakes when moving to topic-based authoring

10 mistakes when moving to topic-based authoring

• 1.
  We’ll start at3 minutes after the hour Make sure your sound is working 10 mistakes when moving to topic-based authoring Sharon Burton Twitter: #10MistakesTBA E-mail: Sharon@sharonburton.com Tweet: Sharonburton
• 2.
  10 mistakes when moving to topic-based authoring Sharon Burton Twitter: #10MistakesTBA E-mail: Sharon@sharonburton.com Tweet: Sharonburton
• 3.
  Twitter: #10MistakesTBA Who amI? ▪ I’m Sharon Burton ▪ Been in the Tech Comm industry for nearly 20 years ▪ Content Consultant ▪ STC Associate Fellow ▪ Teach: ▪ Technical Communication to Engineering students at the University of California, Riverside ▪ Tech Comm certificate program at UCR Extension ▪ Society for Technical Communication Certificate Courses ▪ I knit, design patterns, work out, write, garden, have a large dog, and am all around just fun
• 4.
  Twitter: #10MistakesTBA Supporting roletoday… ▪ Bonni Graham is supporting us ▪ If you have a question, Bonni will help you in the questions window ▪ We’re doing a live Q and A at the end ▪ We’re recording this webinar ▪ Slides are available on SlideShare ▪ Let’s also say “Thank you” to ProSpring Technical Staffing for sponsoring these webinars ▪ http://prospringstaffing.com/ ▪ www.lavacon.org
• 5.
  What is topic-based authoring? Quickdefinition
• 6.
  Twitter: #10MistakesTBA Definition ▪ Topic-basedauthoring 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
• 7.
  What is Topic-basedAuthoring? ▪ 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
• 8.
  Twitter: #10MistakesTBA What isTopic-based Authoring? ▪ 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
• 9.
  Twitter: #10MistakesTBA What isTopic-based Authoring? Library Adding About Programming Users Objects and Relating Inheritance Objects Importing Placing Setting Objects 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
• 10.
  Twitter: #10MistakesTBA What isTopic-based Authoring? 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
• 11.
  What are themistakes? How to mess this up
• 12.
  1: Not gettingbuy-in ▪ This is not going to be an instant and dramatic improvement ▪ Except localization Management and ▪ Costs may drop immediately other teams need to understand ▪ Schedules may be impacted why this is better and you have to ▪ Less content can be scary show that. Maybe a business case?
• 13.
  2: Using thesame tools ▪ The tools that got you into this mess are probably not the tools to get you out Asking Techwr-l ▪ Evaluate what your needs are what they use now and in the future and buying that not the answer. ▪ Work with the vendors closely What are your to make sure what you need is problems and what they can do what are your solutions?
• 14.
  3: Using thesame processes ▪ Developing topic-based content is different ▪ Topics “stand alone” on The processes for content and/or formatting developing, editi ng, and ▪ Topics are reviewed as they publishing a 200 are ready page manual won’t work. ▪ Review process must change ▪ Maybe use a special review product
• 15.
  4: Not trainingpeople ▪ New tools + new process = training ▪ Training provides more than Not training sets how to use the product up projects and ▪ Includes best practices for our people for failure. workflow You can’t expect ▪ Identifies the changes for our people to workflow magically know. ▪ Instantiates how we do what we do
• 16.
  5: Not planningthe move ▪ Your legacy content is not going to fit neatly ▪ It’s at least not well written/structured/ organized ▪ One manual/help may not give you You can’t jump on the real picture your horse and ▪ Especially if you had a lot of contractors, the legacy content has ride off in all been around a long time, and so on directions. Analyze what you ▪ This can be very hard on the staff ▪ People want their content to be the have before you exception decide what you ▪ It’s special content, not like other have content and needs special attention
• 17.
  6: Not usingwriting guidelines ▪ Before we can start thinking about moving to topic-based authoring ▪ And gaining the benefits thereof We must have ▪ Content reuse demands good writing consistent writing standards standards in place. ▪ The content can appear in many places ▪ In more than one deliverable ▪ Everyone cannot write in “their style”
• 18.
  7: Slicing contentaccording to headings ▪ That’s step #1 of x and x is bigger than 2 ▪ Now you need to think about Because most ▪ Content reuse tools allow you to ▪ Smaller topics import and slice your legacy ▪ Embedded topics (snippets) content based on ▪ Localization headings, it can feel like you’re ▪ Outputs done after you ▪ Devices import. ▪ More
• 19.
  8: Not reusingcontent ▪ You can’t reuse what you can’t find ▪ Opportunistic reuse ▪ People remember this content from before Writing content is ▪ Maybe they can find it expensive. ▪ Big time sink Re-creating existing content ▪ Systematic reuse is very expensive. ▪ The system knows this content has Localizing similar been written previously but different is ▪ Prompts the writer for reuse really expensive. ▪ Tracks reuse and reports it
• 20.
  9: Not consideringaudience ▪ Your users are not stupid ▪ They know how to use Windows ▪ They know their jobs Identify your ▪ Most users are intermediate audience and users their schemas. Identify their domains of knowledge. 69% of your users are intermediate level.
• 21.
  10: Thinking thisis trivial ▪ It won’t take any time to figure this out ▪ We can do this as we need to Your legacy content is not ▪ It’s easy going to fit neatly in content ▪ We’ll hire an intern to do it categories. ▪ We can meet deadlines while we completely restructure all our content
• 22.
  11: (Bonus) Wedon’t need to worry about Localization ▪ If you are not localizing now, you will be in the future ▪ If you are localizing now, you Always act like know how complicated it can you’re going to be localize and ▪ Someone will decide to add nothing bad more languages will happen to you. ▪ Because that’s not a problem, right?
• 23.
  More information Resources formore information
• 24.
  Good reading resources ▪Single Sourcing: Building Modular Documentation by Kurt Ament ▪ ISBN-10: 0815514913 or ISBN-13: 978-0815514916 ▪ Content Strategy 101: Transform Technical Content into a Business Asset by Sarah S. O'Keefe and Alan S. Pringle ISBN-10: 0982811845 or ISBN-13: 978-0982811849 ▪ Content Strategy: Connecting the dots between business, brand, and benefits by Rahel Anne Bailie and Noz Urbina ISBN-10: 1937434168 or ISBN-13: 978-1937434168
• 25.
  These are good,too ▪ 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! ▪ 8 Steps to Amazing Webinars, 2012 ISBN-10: 1937434044 ▪ Available from Amazon and Barnes and Noble
• 26.
  Questions? Contact me: E-mail: Sharon@sharonburton.com Twitter: Sharonburton