kai weber - unstructured documentation to structured topics - stc 140519 - public
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
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