Documentation in a Collaborative World: What We've Learned

  • Published on

  • View

  • Download


Documentation in a Collaborative World: What We've Learned -- Examines how two trends, agile programming and collaboration (Web 2.0) are affecting the way we plan and manage technical documentation projects. Describes emerging best practices


1. Documentation in a Collaborative World: What Weve Learned 26 October 2011 Larry Kunz [email_address] Twitter: @larry_kunz 2. Trends New, varied sources for content Collaboration Agile Just in time development (Web 2.0) 3. A New Role for the Doc Plan It is the star to every wandering bark Shakespeare Sonnet 116 4. A New Role for the Doc Plan It is subordinate to the content strategy . 5. Challenges Reviews: Ad hoc, limited in scope Edits: Ditto What to do with legacy content How to integrate localization into the process flickr:jla 6. Best Practices: Tools & Processes Encourage collaboration Structure & reuse 7. Best Practices: Communication Agile is about communication. -- From an STC Editing SIG chat Use developments bug-tracking system Doc reviews during the sprint Finish all user stories (Unfinished stories = unfinished documentation) 8. Best Practices: Reviews Jane Austen, Northanger Abbey Carefully manage and monitor the reviews Dont lose sight of the big picture Comprehensive reviews during final sprints Dont take the advice of Jane Austen: Let us leave it to the reviewers to abuse such effusions of fancy at their leisure. ( Northanger Abbey ) 9. Best Practices: Collaboration Book sprints Close working relationships Careful planning Amusements and diversions 10. Best Practices: Localization Chunking content Consistency Sim-ship: tricky but not impossible 11. Getting It All in the Right Order Organizing Refining Integrating Emphasizing & deemphasizing Content curation 12. The Content Strategy MorgueFile: earl53 Defines guiding principles Encourages contributions Defines roles, workflow, authority Provides for managing content after publication What target are we shooting at? 13. Editing stock.xchng: MikLav Somewhat fictional content Edit and re-edit Edit outlines Lock down content early 14. The Content Management System Allow internal publication Support collaborative writing Synchronize with authoring tools 15. Web Analytics 16. Controversies Content curation Good enough to ship ??? stock.xchng: bluegum 17. Tomorrow stock.xchng: toxygen