Documentation in a Collaborative World: What We've Learned

  • Published on
    07-Nov-2014

  • View
    307

  • Download
    1

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

  • 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