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

16
FROM UNSTRUCTURED DOCUMENTATION TO STRUCTURED TOPICS Kai Weber @techwriterkai #stc14 - 19 May 2014

Upload: amelio

Post on 23-Aug-2014

1.777 views

Category:

Presentations & Public Speaking


3 download

DESCRIPTION

You're sold on the benefits of structured content, but don't know how to begin? This session shows you how to implement topic-based authoring by converting existing unstructured documentation into structured topics in Word. The underlying process works for online help, user manuals, but also other content, such as wiki articles, training materials, etc. Tricky examples receive special attention: How to deal with content when topic types are mixed or when the topic sequence doesn't flow nicely.

TRANSCRIPT

Page 1: Kai Weber  - Unstructured documentation to structured topics - stc 140519 - public

FROM UNSTRUCTURED DOCUMENTATION

TO STRUCTURED TOPICS

Kai Weber

@techwriterkai

#stc14 - 19 May 2014

Page 2: Kai Weber  - Unstructured documentation to structured topics - stc 140519 - public

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

Page 3: Kai Weber  - Unstructured documentation to structured topics - stc 140519 - public

WELCOME!

This is a project walk-through mini-workshop!

Information: Methods, options, risks

Confidence

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

#stc14 @techwriterkai

Page 4: Kai Weber  - Unstructured documentation to structured topics - stc 140519 - public

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

Page 5: Kai Weber  - Unstructured documentation to structured topics - stc 140519 - public

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/

Page 6: Kai Weber  - Unstructured documentation to structured topics - stc 140519 - public

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

Page 7: Kai Weber  - Unstructured documentation to structured topics - stc 140519 - public

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

Page 8: Kai Weber  - Unstructured documentation to structured topics - stc 140519 - public

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

Page 9: Kai Weber  - Unstructured documentation to structured topics - stc 140519 - public

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

Page 10: Kai Weber  - Unstructured documentation to structured topics - stc 140519 - public

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

Page 11: Kai Weber  - Unstructured documentation to structured topics - stc 140519 - public

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

Page 12: Kai Weber  - Unstructured documentation to structured topics - stc 140519 - public

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

Page 13: Kai Weber  - Unstructured documentation to structured topics - stc 140519 - public

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

Page 14: Kai Weber  - Unstructured documentation to structured topics - stc 140519 - public

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

Page 15: Kai Weber  - Unstructured documentation to structured topics - stc 140519 - public

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

Page 16: Kai Weber  - Unstructured documentation to structured topics - stc 140519 - public

THANK YOU! KEEP IN TOUCH!

kaiweber.wordpress.com

@techwriterkai