10 mistakes when moving to topic-based authoring

10 mistakes when moving to topic-based authoring

Sharon BurtonE-mail: [email protected] Tweet: Sharonburton

We’ll start at 3 minutes after the hour

Make sure your sound is working

Twitter: #10MistakesTBA

10 mistakes when moving to topic-based authoring

Sharon BurtonE-mail: [email protected] Tweet: Sharonburton

Twitter: #10MistakesTBA

Who 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: #10MistakesTBA

Supporting 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

Twitter: #10MistakesTBA

What is topic-based authoring?

Quick definition

Definition

▪ 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

Twitter: #10MistakesTBA

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

What 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: #10MistakesTBA

Library

What is Topic-based Authoring?

Printing Reports

Using Container Objects

Saving reports

Creating

Reports

About Schedu

les

Adding Users

Setting Permissions

Deleting

Users

Placing Objects About

Objects

About Users

Exporting

Objects

About Containment

Customizing

Objects

About Programming

Objects and

Inheritance

Editing Reports

Containing

Objects

Relating Objects

Importing

Reports

Setting Schedules

About Report

s

Twitter: #10MistakesTBA

Library

What is Topic-based Authoring?

Admin Guide

•About Users•Adding Users•Deleting Users•Setting Permissions

•About Reports•Creating Reports•Editing Reports•Saving Reports•Printing Reports•Importing Reports

Programmers Guide

•About Programming•About Objects•Placing Objects•About Containment•Objects and Inheritance •Using Container Objects

•Customizing Objects•Relating Objects

Getting Started

•About Users•About Reports•About Programming•About Objects•About Containment•Exporting Objects•About Schedules

Twitter: #10MistakesTBA

What are the mistakes?

How to mess this up

1: Not getting buy-in

Management and other teams need to understand why this is better and you have to show that. Maybe a business case?

▪ This is not going to be an instant and dramatic improvement▪ Except localization▪ Costs may drop

immediately

▪ Schedules may be impacted

▪ Less content can be scary

2: Using the same tools

Asking Techwr-l what they use and buying that not the answer. What are your problems and what are your solutions?

▪ The tools that got you into this mess are probably not the tools to get you out

▪ 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

3: Using the same processes

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

4: Not training people

Not training sets up projects and people for failure. You can’t expect people to magically know.

▪ New tools + new process = training

▪ 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

5: Not planning the move

You can’t jump on your horse and ride off in all directions. Analyze what you have before you decide what you have

▪ 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 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 on the staff▪ People want their content to be the

exception▪ It’s special content, not like other

content and needs special attention

6: Not using writing guidelines

We must have good writing standards in place.

▪ Before we can start thinking about moving to topic-based authoring▪ And gaining the benefits

thereof

▪ Content reuse demands consistent writing standards▪ The content can appear in

many places▪ In more than one deliverable

▪ Everyone cannot write in “their style”

7: Slicing content according to headings

Because most tools allow you to import and slice your legacy content based on headings, it can feel like you’re done after 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▪ Outputs▪ Devices▪ More

8: Not reusing content

Writing content is expensive. Re-creating existing content is very expensive. Localizing similar but different is really 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

9: Not considering audience

Identify your audience and their schemas. Identify their domains of knowledge. 69% of your users are intermediate level.

▪ Your users are not stupid▪ They know how to use

Windows▪ They know their jobs

▪ Most users are intermediate users

10: Thinking this is trivial

Your legacy content is not 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

11: (Bonus) We don’t need to worry about Localization

Always act like you’re going to localize and nothing bad will happen to you.

▪ If you are not localizing now, you will be in the future

▪ If you are localizing now, you know how complicated it can be▪ Someone will decide to

add more languages▪ Because that’s not a

problem, right?

More information

Resources 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 Assetby Sarah S. O'Keefe and Alan S. PringleISBN-10: 0982811845 or ISBN-13: 978-0982811849

▪ Content Strategy: Connecting the dots between business, brand, and benefits by Rahel Anne Bailie and Noz UrbinaISBN-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, 2012ISBN-10: 1937434044▪ Available from Amazon and Barnes and Noble

Questions?

Contact me:E-mail: [email protected] Twitter: Sharonburton