Documentation in a Collaborative World: What We've Learned

Download Documentation in a Collaborative World: What We've Learned

Post on 07-Nov-2014

310 views

Category:

Business

1 download

DESCRIPTION

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

TRANSCRIPT

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