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 Kunzlkunz@sdicorp.comTwitter: @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