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 @tec...
WELCOME!
This is a project walk-through mini-workshop! 
 Information: Methods, options, risks
 Confidence
! Apply to yo...
PROGRAM
What’s a topic
1. Create a content model
2. Identify topic types
3. Re-chunk your content
4. Sequence your topics
...
WHAT’S A TOPIC
Topics
 Modular chunks of content
 About a specific subject
 Have an identifiable purpose
 Can stand al...
WHY CREATE A CONTENT MODEL FOR TOPICS
To ensure consistent structure
 Defines topic types
 Concepts, tasks, reference, e...
1. CREATE A CONTENT MODEL
Define topic types by use case
 Concepts to explain the “what”
 Tasks to guide the “how”
 Ref...
1. CREATE A CONTENT MODEL
Define elements and structure per topic type
1. Introduction/context, optional
2. Prerequisite, ...
2. IDENTIFY TOPIC TYPES IN EXISTING CONTENT
Audit content, take it apart
1. Start with mature content
2. Take it to pieces...
3. RE-CHUNK CONTENT INTO TRUE TOPICS
Re-assemble pieces according to content model
Left-over content?
Incomplete topics?
“...
4. SEQUENCE YOUR TOPICS
Create a useful content structure
 Organise contents by use case
 Concepts before tasks
 Setup ...
5. WRITE GOOD HEADINGS FOR YOUR TOPICS
Show how topics fit in and what’s in ‘em
 Support your doc strategy
 Address user...
6. LINK RELATED TOPICS
Link to ensure that every page can be page one
 “Scent of information” (Baker)
 (Re-)connect topi...
STAY ON TRACK
Ensure focus
 Treat content as a corporate asset
 Get management buy-in and resources
 Acquire expertise ...
STAY ON TRACK
Ensure focus
 Treat content as a corporate asset
 Get management buy-in and resources
 Acquire expertise ...
THANK YOU! KEEP IN TOUCH!
kaiweber.wordpress.com
@techwriterkai
Nächste SlideShare
Wird geladen in …5
×

Kai Weber - Unstructured documentation to structured topics - stc 140519 - public

11.475 Aufrufe

Veröffentlicht am

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.

0 Kommentare
3 Gefällt mir
Statistik
Notizen
  • Als Erste(r) kommentieren

Keine Downloads
Aufrufe
Aufrufe insgesamt
11.475
Auf SlideShare
0
Aus Einbettungen
0
Anzahl an Einbettungen
8.475
Aktionen
Geteilt
0
Downloads
47
Kommentare
0
Gefällt mir
3
Einbettungen 0
Keine Einbettungen

Keine Notizen für die Folie

Kai Weber - Unstructured documentation to structured topics - stc 140519 - public

  1. 1. FROM UNSTRUCTURED DOCUMENTATION TO STRUCTURED TOPICS Kai Weber @techwriterkai #stc14 - 19 May 2014
  2. 2. WELCOME! This is a project walk-through mini-workshop!  ! Apply to your situation, take notes, ask questions! #stc14 @techwriterkai PhotobySteinarTalmoen
  3. 3. WELCOME! This is a project walk-through mini-workshop!   Information: Methods, options, risks  Confidence ! Apply to your situation, take notes, ask questions! #stc14 @techwriterkai
  4. 4. 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
  5. 5. 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/
  6. 6. 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
  7. 7. 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
  8. 8. 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
  9. 9. 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
  10. 10. 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
  11. 11. 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
  12. 12. 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
  13. 13. 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
  14. 14. 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
  15. 15. 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
  16. 16. THANK YOU! KEEP IN TOUCH! kaiweber.wordpress.com @techwriterkai

×