documentation in a collaborative world: what we've learned
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 practicesTRANSCRIPT
Documentation in a Collaborative Documentation in a Collaborative World:World:
What We’ve LearnedWhat We’ve Learned26 October 2011
Larry [email protected]: @larry_kunz
TrendsTrends
New, varied sources for content
“Just in time” development
A New Role for the Doc PlanA New Role for the Doc Plan
It is the star to every wandering bark… Shakespeare – Sonnet 116
A New Role for the Doc PlanA New Role for the Doc Plan
It is subordinate to the content strategy.
ChallengesChallenges
flickr:júlía ∆
Reviews: Ad hoc, limited in scope
Edits: Ditto
What to do with legacycontent
How to integrate localizationinto the process
Best Practices: Tools & ProcessesBest Practices: Tools & Processes
Encouragecollaboration
Structure& reuse
Best Practices: CommunicationBest Practices: Communication
“Agile is about communication.” -- From an STC Editing SIG chat
Use development’sbug-tracking system
Doc reviews during the sprint
Finish all user stories(Unfinished stories = unfinished documentation)
Best Practices: ReviewsBest Practices: Reviews
– Jane Austen, Northanger Abbey
Carefully manage and monitorthe reviews
Don’t lose sight of the big picture
Comprehensive reviews duringfinal sprints
Don’t take the advice of Jane Austen: Let us leave it to the reviewers to abuse sucheffusions of fancy at their leisure.
(Northanger Abbey)
Best Practices: CollaborationBest Practices: CollaborationBook sprints Close working relationships
Careful planning
Amusements and diversions
Best Practices: LocalizationBest Practices: Localization
Chunking content
Consistency
Sim-ship: tricky but not impossible
Getting It All in the Right OrderGetting It All in the Right Order Organizing
Refining
Integrating
Emphasizing& deemphasizing
Content curation
The Content StrategyThe Content Strategy
MorgueFile: earl53
Defines guiding principles
Encourages contributions
Defines roles, workflow, authority
Provides for managing contentafter publication
What target are we shooting at?
EditingEditing
stock.xchng: MikLav
“Somewhat fictional” content
Edit and re-edit
Edit outlines
Lock down content early
The Content Management SystemThe Content Management System
Allow internal publication
Support collaborative writing
Synchronize with authoring tools
Web AnalyticsWeb Analytics
ControversiesControversies
Content curation
“Good enoughto ship” ???
stock.xchng: bluegum
TomorrowTomorrow
stock.xchng: toxygen