Managing Documentation Projects in a Collaborative World


Published on

Managing Documentation Projects in a Collaborative World
Presentation at STC Summit: 4 May 2010

Published in: Technology
1 Comment
  • Great overview. Thanks for sharing!
    Are you sure you want to  Yes  No
    Your message goes here
No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

Managing Documentation Projects in a Collaborative World

  1. 1. Managing Documentation Projects in a Collaborative World Technical Communication Summit May 2010 Larry Kunz [email_address] Twitter: larry_kunz
  2. 2. Outline <ul><li>The changing process for developing technical documentation </li></ul><ul><li>Trends that are bringing changes </li></ul><ul><ul><li>Web 2.0 </li></ul></ul><ul><ul><li>Agile </li></ul></ul><ul><li>Challenges and solutions </li></ul><ul><li>Where do we go from here? </li></ul>
  3. 3. Let’s collaborate…. <ul><li>Twitter: #stc10 or #pmcollab </li></ul><ul><li>My blog: </li></ul>
  4. 4. The Traditional Process <ul><li>Long development cycles </li></ul><ul><li>Static “official” documentation products </li></ul><ul><li>Gathering content </li></ul><ul><li>Writers sometimes isolated from product developers </li></ul><ul><li>Write/Review /Edit/R epeat… then Publish </li></ul>
  5. 5. The Doc Plan <ul><li>It is the star to every wandering bark… </li></ul><ul><li>Shakespeare – Sonnet 116 </li></ul>
  6. 6. The Process: 30 Years Ago
  7. 7. The Process: 10 Years Ago
  8. 8. The Process: Today
  9. 9. The New Traditional Process <ul><li>Short long development cycles </li></ul><ul><li>Dynamic, community-sourced Static “official” documentation products </li></ul><ul><li>Collaborative Gathering content </li></ul><ul><li>Writers must be in close touch with sometimes isolated from product developers </li></ul><ul><li>Write/Review/ Publish /Edit /Repeat </li></ul>
  10. 10. Trends that are Changing the Process <ul><li>Web 2.0 (and beyond): New, varied sources for content How can I keep track of—much less control—the flow of content? </li></ul><ul><li>Agile methodology: “Just in time” development Hey, what does that do to my doc plan? </li></ul>
  11. 11. Web 1.0, 2.0, 3.0 <ul><li>Web 1.0: One-way information flow </li></ul><ul><ul><li>Static publishing </li></ul></ul><ul><ul><li>No interaction </li></ul></ul><ul><li>Web 2.0: From publishing to participation </li></ul><ul><ul><li>Information sharing and collaboration </li></ul></ul><ul><ul><li>User-generated content </li></ul></ul><ul><ul><li>The community </li></ul></ul><ul><li>Web 3.0: Marketing buzzword, or unrealized vision? </li></ul><ul><ul><li>“ Intelligent Web 2.0” </li></ul></ul><ul><ul><li>Semantic Web, personalization, intelligent search, mobility </li></ul></ul><ul><li>(Source: J. Leigh Brown and Peg Mulligan) </li></ul>
  12. 12. Web 2.0 and Publishing <ul><li>From publishing to participation </li></ul><ul><ul><li>Doc sprints, FLOSS manuals </li></ul></ul><ul><ul><li>User-generated content augments and even supplants the “official” documentation </li></ul></ul><ul><li>The concept of the community </li></ul>
  13. 13. Web 2.0 and Publishing <ul><li>Example: Adobe Community Help </li></ul>
  14. 14. Web 2.0 and Publishing <ul><li>If you build it, they won’t just come </li></ul><ul><li>You have to </li></ul><ul><ul><li>Invite participation </li></ul></ul><ul><ul><li>Make it easy </li></ul></ul><ul><ul><li>Give prominence to UGC </li></ul></ul>
  15. 15. Web 2.0 and Publishing <ul><li>You need a content strategy </li></ul><ul><ul><li>Creating content </li></ul></ul><ul><ul><li>Delivering content </li></ul></ul><ul><ul><li>Governing content </li></ul></ul>
  16. 16. The Content Strategist <ul><li>“ Curator” – not “gatekeeper” </li></ul><ul><li>Keeps the big picture in mind </li></ul><ul><li>Manages content throughout the content lifecycle </li></ul><ul><li>Enforces a strategy that’s repeatable </li></ul>
  17. 17. The Agile Manifesto <ul><li>We value: </li></ul><ul><li>Individuals and interactions over processes and tools </li></ul><ul><li>Working software over comprehensive documentation </li></ul><ul><li>Customer collaboration over contract negotiation </li></ul><ul><li>Responding to change over following a plan </li></ul><ul><li>That is, while there is value in the items on the right… ….We value the items on the left more. </li></ul>
  18. 18. An Agile documentation project <ul><li>Small, tightly knit teams </li></ul><ul><ul><li>Scrums </li></ul></ul><ul><ul><li>Writers have to be fully involved </li></ul></ul><ul><li>Modular writing </li></ul><ul><ul><li>Focused on major needs of the user </li></ul></ul><ul><ul><li>Topic based </li></ul></ul>
  19. 19. An Agile documentation project <ul><li>User stories </li></ul><ul><ul><li>They drive the product and the docs </li></ul></ul><ul><ul><li>Basis for your audience analysis </li></ul></ul><ul><li>Short development cycles </li></ul><ul><ul><li>Sprints </li></ul></ul><ul><ul><li>Geared to being flexible </li></ul></ul><ul><ul><li>How quickly can you publish? </li></ul></ul>
  20. 20. An Agile documentation project <ul><li>The doc plan is subsumed by the content strategy </li></ul>
  21. 21. Principles for Writing in Agile <ul><li>From Anne Gentle’s Just Write Click blog </li></ul><ul><li>Only deliver things that an actual customer would find useful. </li></ul><ul><li>List and prioritize all tasks that get you incrementally closer to your goals. </li></ul><ul><li>Understand the business goals. Ask questions and seek details. </li></ul><ul><li>Deliver something that the team considers to be done, shippable, and customer- ready . </li></ul>
  22. 22. An Agile documentation project <ul><li>New wine into old wineskins? </li></ul><ul><li>No. </li></ul><ul><li>New wine into new wineskins. </li></ul><ul><li>(St. Mark 2:22) </li></ul>
  23. 23. Web 2.0 and Agile Challenges and Solutions
  24. 24. Web 2.0 and Agile: Challenges <ul><li>Reviews are often ad hoc and very limited in scope </li></ul><ul><li>How to edit </li></ul><ul><li>What to do with legacy information </li></ul><ul><li>How to plan for localization/translation </li></ul>
  25. 25. Challenge: Reviews <ul><li>Very few SMEs involved </li></ul><ul><li>Hard to squeeze into the iteration schedule </li></ul><ul><li>Topic-based reviews don’t provide the big picture </li></ul>
  26. 26. Solutions: Reviews <ul><li>Make sure that Tech Pubs is a full member of the team </li></ul><ul><li>Find a champion </li></ul><ul><li>Conduct targeted reviews </li></ul><ul><li>You might need a special “big picture” review </li></ul><ul><li>Keep track </li></ul>
  27. 27. Challenge: Editing <ul><li>Editing can’t be a one-time event </li></ul><ul><li>A comprehensive edit isn’t possible </li></ul><ul><li>Writing teams might not know each other – or the editors </li></ul><ul><li>Content comes from nontraditional sources </li></ul>
  28. 28. Solutions: Editing <ul><li>Editing as an ongoing process </li></ul><ul><li>Topic-based editing </li></ul><ul><li>The editor is still part of the team – working closely with PM and content strategist </li></ul><ul><li>Style guides are vital </li></ul>
  29. 29. Challenge: Legacy Content <ul><li>Easy to overlook in sprint-based reviews </li></ul><ul><li>Reviewers don’t see new and changed content in context </li></ul><ul><li>Scrum team members don’t have time to review old content </li></ul>
  30. 30. Solutions: Legacy Content <ul><li>Don’t skip the content inventory! </li></ul><ul><li>Content is best reviewed by an experienced SME </li></ul><ul><li>Review can be done at any time </li></ul><ul><li>Help the SME by laying out the ground rules </li></ul>
  31. 31. Challenge: Localization <ul><li>Scheduling translation </li></ul><ul><li>Handling changes to the product content </li></ul>
  32. 32. Solutions: Localization <ul><li>Break the translation into pieces </li></ul><ul><li>Align the translation schedule with your iterations </li></ul><ul><li>Take advantage of the processes your software developers are following </li></ul>
  33. 33. Evolving a set of best practices <ul><li>We’re still learning </li></ul><ul><li>Let’s share the things we learn </li></ul><ul><li>What new trends are coming? </li></ul>
  34. 34. Resources <ul><li>Bailie, Rahel: “Rahel Bailie Provides A Content Strategy Primer,” Sept. 2009 (article at </li></ul><ul><li>Gentle, Anne: Conversation and Community: The Social Web for Documentation </li></ul><ul><li>Halvorson, Kristina: Content Strategy for the Web </li></ul><ul><li>Hamilton, Richard: Managing Writers: A Real World Guide to Managing Technical Documentation </li></ul><ul><li>Sheffield, Richard: The Web Content Strategist's Bible: The Complete Guide To a New and Lucrative Career for Writers of All Kinds </li></ul>
  35. 35. Your turn Q & A