Managing Documentation Projects in a Collaborative World

  • Published on
    04-Feb-2015

  • View
    2.776

  • Download
    16

Embed Size (px)

DESCRIPTION

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

Transcript

<ul><li> 1. Managing Documentation Projects in a Collaborative World Technical Communication Summit May 2010 Larry Kunz [email_address] www.sdicorp.com Twitter: larry_kunz </li> <li> 2. Outline <ul><li>The changing process for developing technical documentation </li></ul><ul><li>Trends that are bringing changes </li></ul><ul><li><ul><li>Web 2.0 </li></ul></li></ul><ul><li><ul><li>Agile </li></ul></li></ul><ul><li>Challenges and solutions </li></ul><ul><li>Where do we go from here? </li></ul></li> <li> 3. Lets collaborate. <ul><li>Twitter: #stc10 or #pmcollab </li></ul><ul><li>My blog: http://bit.ly/bsE2PH </li></ul></li> <li> 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></li> <li> 5. The Doc Plan <ul><li>It is the star to every wandering bark </li></ul><ul><li>Shakespeare Sonnet 116 </li></ul></li> <li> 6. The Process: 30 Years Ago </li> <li> 7. The Process: 10 Years Ago </li> <li> 8. The Process: Today </li> <li> 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></li> <li> 10. Trends that are Changing the Process <ul><li>Web 2.0 (and beyond): New, varied sources for content How can I keep track ofmuch less controlthe flow of content? </li></ul><ul><li>Agile methodology: Just in time development Hey, what does that do to my doc plan? </li></ul></li> <li> 11. Web 1.0, 2.0, 3.0 <ul><li>Web 1.0: One-way information flow </li></ul><ul><li><ul><li>Static publishing </li></ul></li></ul><ul><li><ul><li>No interaction </li></ul></li></ul><ul><li>Web 2.0: From publishing to participation </li></ul><ul><li><ul><li>Information sharing and collaboration </li></ul></li></ul><ul><li><ul><li>User-generated content </li></ul></li></ul><ul><li><ul><li>The community </li></ul></li></ul><ul><li>Web 3.0: Marketing buzzword, or unrealized vision? </li></ul><ul><li><ul><li> Intelligent Web 2.0 </li></ul></li></ul><ul><li><ul><li>Semantic Web, personalization, intelligent search, mobility </li></ul></li></ul><ul><li>(Source: J. Leigh Brown and Peg Mulligan) </li></ul></li> <li> 12. Web 2.0 and Publishing <ul><li>From publishing to participation </li></ul><ul><li><ul><li>Doc sprints, FLOSS manuals </li></ul></li></ul><ul><li><ul><li>User-generated content augments and even supplants the official documentation </li></ul></li></ul><ul><li>The concept of the community </li></ul></li> <li> 13. Web 2.0 and Publishing <ul><li>Example: Adobe Community Help </li></ul></li> <li> 14. Web 2.0 and Publishing <ul><li>If you build it, they wont just come </li></ul><ul><li>You have to </li></ul><ul><li><ul><li>Invite participation </li></ul></li></ul><ul><li><ul><li>Make it easy </li></ul></li></ul><ul><li><ul><li>Give prominence to UGC </li></ul></li></ul></li> <li> 15. Web 2.0 and Publishing <ul><li>You need a content strategy </li></ul><ul><li><ul><li>Creating content </li></ul></li></ul><ul><li><ul><li>Delivering content </li></ul></li></ul><ul><li><ul><li>Governing content </li></ul></li></ul></li> <li> 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 thats repeatable </li></ul></li> <li> 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></li> <li> 18. An Agile documentation project <ul><li>Small, tightly knit teams </li></ul><ul><li><ul><li>Scrums </li></ul></li></ul><ul><li><ul><li>Writers have to be fully involved </li></ul></li></ul><ul><li>Modular writing </li></ul><ul><li><ul><li>Focused on major needs of the user </li></ul></li></ul><ul><li><ul><li>Topic based </li></ul></li></ul></li> <li> 19. An Agile documentation project <ul><li>User stories </li></ul><ul><li><ul><li>They drive the product and the docs </li></ul></li></ul><ul><li><ul><li>Basis for your audience analysis </li></ul></li></ul><ul><li>Short development cycles </li></ul><ul><li><ul><li>Sprints </li></ul></li></ul><ul><li><ul><li>Geared to being flexible </li></ul></li></ul><ul><li><ul><li>How quickly can you publish? </li></ul></li></ul></li> <li> 20. An Agile documentation project <ul><li>The doc plan is subsumed by the content strategy </li></ul></li> <li> 21. Principles for Writing in Agile <ul><li>From Anne Gentles 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></li> <li> 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></li> <li> 23. Web 2.0 and Agile Challenges and Solutions </li> <li> 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></li> <li> 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 dont provide the big picture </li></ul></li> <li> 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></li> <li> 27. Challenge: Editing <ul><li>Editing cant be a one-time event </li></ul><ul><li>A comprehensive edit isnt 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></li> <li> 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></li> <li> 29. Challenge: Legacy Content <ul><li>Easy to overlook in sprint-based reviews </li></ul><ul><li>Reviewers dont see new and changed content in context </li></ul><ul><li>Scrum team members dont have time to review old content </li></ul></li> <li> 30. Solutions: Legacy Content <ul><li>Dont 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></li> <li> 31. Challenge: Localization <ul><li>Scheduling translation </li></ul><ul><li>Handling changes to the product content </li></ul></li> <li> 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></li> <li> 33. Evolving a set of best practices <ul><li>Were still learning </li></ul><ul><li>Lets share the things we learn </li></ul><ul><li>What new trends are coming? </li></ul></li> <li> 34. Resources <ul><li>Bailie, Rahel: Rahel Bailie Provides A Content Strategy Primer, Sept. 2009 (article at http://thecontentwrangler.com) </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></li> <li> 35. Your turn Q &amp; A </li> </ul>