kai weber - unstructured documentation to structured topics - stc 140519 - public

FROM UNSTRUCTURED DOCUMENTATION

TO STRUCTURED TOPICS

Kai Weber

@techwriterkai

#stc14 - 19 May 2014

WELCOME!

This is a project walk-through mini-workshop!

! Apply to your situation, take notes, ask questions!

#stc14 @techwriterkai

Ph

oto

by S

tein

ar T

alm

oen

WELCOME!

This is a project walk-through mini-workshop!

Information: Methods, options, risks

Confidence

! Apply to your situation, take notes, ask questions!

#stc14 @techwriterkai

PROGRAM

What’s a topic

1. Create a content model

2. Identify topic types

3. Re-chunk your content

4. Sequence your topics

5. Write good headings

6. Link related topics

Stay on track

! Apply to your situation, take notes, ask questions!

#stc14 @techwriterkai

WHAT’S A TOPIC

Topics

Modular chunks of content

About a specific subject

Have an identifiable purpose

Can stand alone

Reusable

#stc14 @techwriterkai

http://everypageispageone.com/

WHY CREATE A CONTENT MODEL FOR TOPICS

To ensure consistent structure

Defines topic types

Concepts, tasks, reference, etc.

Defines elements and

their sequence per topic type

! For users Easier and faster to navigate

! For tech comm Easier to maintain, re-use elements

! For companies Easier to “leverage content assets”

#stc14 @techwriterkai

1. CREATE A CONTENT MODEL

Define topic types by use case

Concepts to explain the “what”

Tasks to guide the “how”

Reference to provide technical details

Training to teach for retention

Business cases to argue profitability

! Identify personas, user groups or scenarios per type

! Involve all stakeholders from the beginning

! Ensure that topic types play nicely with each other

#stc14 @techwriterkai

1. CREATE A CONTENT MODEL

Define elements and structure per topic type

1. Introduction/context, optional

2. Prerequisite, optional

3. Instructional steps

4. Result, optional

5. Next steps, optional

6. Error handling, optional

! Use mature content as template and test

! Make elements mutually exclusive between types

! Balance topic structure and flexibility

#stc14 @techwriterkai

2. IDENTIFY TOPIC TYPES IN EXISTING CONTENT

Audit content, take it apart

1. Start with mature content

2. Take it to pieces, literally

3. Sort paragraphs by

topic element and purpose

4. Scrutinize piles with

few or ill-fitting pieces

! First chance to toss out redundant content

! First reality check for your content model

! Balance adjustments to content and model

#stc14 @techwriterkai

3. RE-CHUNK CONTENT INTO TRUE TOPICS

Re-assemble pieces according to content model

Left-over content?

Incomplete topics?

“Ornery topics”?

! Second reality check for your content model

! You can bend a flexible model, but don’t break it!

#stc14 @techwriterkai

If redundant or obsolete, remove

Else turn into new topics

Add content per topic element

Straighten out by topic type

4. SEQUENCE YOUR TOPICS

Create a useful content structure

Organise contents by use case

Concepts before tasks

Setup before operations

Overview above specifics

Glue topics for orientation

Create and adjust topics

Stay consistent in topics, sections, deliverables

Use as many topics as necessary, as few as possible

! Reality check for your new topic chunks

#stc14 @techwriterkai

5. WRITE GOOD HEADINGS FOR YOUR TOPICS

Show how topics fit in and what’s in ‘em

Support your doc strategy

Address user tasks or goals

Create recognizable patterns

Consider use of headings

Labels in links

Search result hits

#stc14 @techwriterkai

6. LINK RELATED TOPICS

Link to ensure that every page can be page one

“Scent of information” (Baker)

(Re-)connect topic types

Concepts <> tasks

Setup topics <> operation topics

#stc14 @techwriterkai

STAY ON TRACK

Ensure focus

Treat content as a corporate asset

Get management buy-in and resources

Acquire expertise (learn or buy)

Baker, Mark. Every Page is Page One. XML Press, 2013.

Bellamy, Laura, et al. DITA Best Practices. IBM Press, 2012.

Hackos, JoAnn. Information Development. Wiley, 2007.

Weber, Kai. “From Unstructured Documentation to Structured

Topics.” STC Proceedings, 2014.

#stc14 @techwriterkai

STAY ON TRACK

Ensure focus

Treat content as a corporate asset

Get management buy-in and resources

Acquire expertise (learn or buy)

Manage the project

1. Define scope & schedule, stick to it

2. Involve stakeholders, manage change

3. Select, run, and evaluate a pilot

4. Iterate conversion of legacy contents

5. Monitor quality and execution

#stc14 @techwriterkai

THANK YOU! KEEP IN TOUCH!

kaiweber.wordpress.com

@techwriterkai