documentation in a collaborative world: what we've learned

17
Documentation in a Documentation in a Collaborative World: Collaborative World: What We’ve Learned What We’ve Learned 26 October 2011 Larry Kunz [email protected] Twitter: @larry_kunz

Upload: larry-kunz

Post on 07-Nov-2014

324 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

Page 1: Documentation in a Collaborative World: What We've Learned

Documentation in a Collaborative Documentation in a Collaborative World:World:

What We’ve LearnedWhat We’ve Learned26 October 2011

Larry [email protected]: @larry_kunz

Page 2: Documentation in a Collaborative World: What We've Learned

TrendsTrends

New, varied sources for content

“Just in time” development

Page 3: Documentation in a Collaborative World: What We've Learned

A New Role for the Doc PlanA New Role for the Doc Plan

It is the star to every wandering bark… Shakespeare – Sonnet 116

Page 4: Documentation in a Collaborative World: What We've Learned

A New Role for the Doc PlanA New Role for the Doc Plan

It is subordinate to the content strategy.

Page 5: Documentation in a Collaborative World: What We've Learned

ChallengesChallenges

flickr:júlía ∆

Reviews: Ad hoc, limited in scope

Edits: Ditto

What to do with legacycontent

How to integrate localizationinto the process

Page 6: Documentation in a Collaborative World: What We've Learned

Best Practices: Tools & ProcessesBest Practices: Tools & Processes

Encouragecollaboration

Structure& reuse

Page 7: Documentation in a Collaborative World: What We've Learned

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)

Page 8: Documentation in a Collaborative World: What We've Learned

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)

Page 9: Documentation in a Collaborative World: What We've Learned

Best Practices: CollaborationBest Practices: CollaborationBook sprints Close working relationships

Careful planning

Amusements and diversions

Page 10: Documentation in a Collaborative World: What We've Learned

Best Practices: LocalizationBest Practices: Localization

Chunking content

Consistency

Sim-ship: tricky but not impossible

Page 11: Documentation in a Collaborative World: What We've Learned

Getting It All in the Right OrderGetting It All in the Right Order Organizing

Refining

Integrating

Emphasizing& deemphasizing

Content curation

Page 12: Documentation in a Collaborative World: What We've Learned

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?

Page 13: Documentation in a Collaborative World: What We've Learned

EditingEditing

stock.xchng: MikLav

“Somewhat fictional” content

Edit and re-edit

Edit outlines

Lock down content early

Page 14: Documentation in a Collaborative World: What We've Learned

The Content Management SystemThe Content Management System

Allow internal publication

Support collaborative writing

Synchronize with authoring tools

Page 15: Documentation in a Collaborative World: What We've Learned

Web AnalyticsWeb Analytics

Page 16: Documentation in a Collaborative World: What We've Learned

ControversiesControversies

Content curation

“Good enoughto ship” ???

stock.xchng: bluegum

Page 17: Documentation in a Collaborative World: What We've Learned

TomorrowTomorrow

stock.xchng: toxygen