Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

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
  • Login to see the comments

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