10 mistakes when moving to topic-based authoringPresentation Transcript
We’ll start at 3 minutes after the hour Make sure your sound is working 10 mistakes when moving to topic-based authoringSharon Burton Twitter: #10MistakesTBAE-mail: Sharon@sharonburton.comTweet: Sharonburton
10 mistakes when moving to topic-based authoringSharon Burton Twitter: #10MistakesTBAE-mail: Sharon@sharonburton.comTweet: Sharonburton
Twitter: #10MistakesTBAWho am I?▪ 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
Twitter: #10MistakesTBASupporting role today…▪ 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
What is topic-basedauthoring?Quick definition
Twitter: #10MistakesTBADefinition▪ 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
What is Topic-based Authoring?▪ 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
Twitter: #10MistakesTBAWhat is Topic-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
Twitter: #10MistakesTBAWhat is Topic-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
Twitter: #10MistakesTBAWhat is Topic-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
What are the mistakes?How to mess this up
1: Not getting buy-in ▪ This is not going to be an instant and dramatic improvement ▪ Except localizationManagement and ▪ Costs may drop immediatelyother teams needto understand ▪ Schedules may be impactedwhy this is betterand you have to ▪ Less content can be scaryshow that.Maybe a businesscase?
2: Using the same tools ▪ The tools that got you into this mess are probably not the tools to get you outAsking Techwr-l ▪ Evaluate what your needs arewhat they use now and in the futureand buying thatnot the answer. ▪ Work with the vendors closelyWhat are your to make sure what you need isproblems and what they can dowhat are yoursolutions?
3: Using the same processes ▪ Developing topic-based content is different ▪ Topics “stand alone” onThe processes for content and/or formattingdeveloping, editing, and ▪ Topics are reviewed as theypublishing a 200 are readypage manualwon’t work. ▪ Review process must change ▪ Maybe use a special review product
4: Not training people ▪ New tools + new process = training ▪ Training provides more thanNot training sets how to use the productup projects and ▪ Includes best practices for ourpeople for failure. workflowYou can’t expect ▪ Identifies the changes for ourpeople to workflowmagically know. ▪ Instantiates how we do what we do
5: Not planning the 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 youYou can’t jump on the real pictureyour horse and ▪ Especially if you had a lot of contractors, the legacy content hasride off in all been around a long time, and so ondirections.Analyze what you ▪ This can be very hard on the staff ▪ People want their content to be thehave before you exceptiondecide what you ▪ It’s special content, not like otherhave content and needs special attention
6: Not using writing guidelines ▪ Before we can start thinking about moving to topic-based authoring ▪ And gaining the benefits thereofWe must have ▪ Content reuse demandsgood writing consistent writing standardsstandards inplace. ▪ The content can appear in many places ▪ In more than one deliverable ▪ Everyone cannot write in “their style”
7: Slicing content according toheadings ▪ That’s step #1 of x and x is bigger than 2 ▪ Now you need to think aboutBecause most ▪ Content reusetools allow you to ▪ Smaller topicsimport and sliceyour legacy ▪ Embedded topics (snippets)content based on ▪ Localizationheadings, it canfeel like you’re ▪ Outputsdone after you ▪ Devicesimport. ▪ More
8: Not reusing content ▪ You can’t reuse what you can’t find ▪ Opportunistic reuse ▪ People remember this content from beforeWriting content is ▪ Maybe they can find itexpensive. ▪ Big time sinkRe-creatingexisting content ▪ Systematic reuseis very expensive. ▪ The system knows this content hasLocalizing similar been written previouslybut different is ▪ Prompts the writer for reusereally expensive. ▪ Tracks reuse and reports it
9: Not considering audience ▪ Your users are not stupid ▪ They know how to use Windows ▪ They know their jobsIdentify your ▪ Most users are intermediateaudience and userstheir schemas.Identify theirdomains ofknowledge.69% of your usersare intermediatelevel.
10: Thinking this is trivial ▪ It won’t take any time to figure this out ▪ We can do this as we need toYour legacycontent is not ▪ It’s easygoing to fit neatlyin content ▪ We’ll hire an intern to do itcategories. ▪ We can meet deadlines while we completely restructure all our content
11: (Bonus) We don’t need to worryabout Localization ▪ If you are not localizing now, you will be in the future ▪ If you are localizing now, youAlways act like know how complicated it canyou’re going to belocalize and ▪ Someone will decide to addnothing bad more languageswill happen toyou. ▪ Because that’s not a problem, right?
More informationResources for more information
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. OKeefe 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
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