Managing Documentation Projects in a Collaborative World

Managing Documentation Projects in a Collaborative World Technical Communication Summit May 2010 Larry Kunz [email_address] www.sdicorp.com Twitter: larry_kunz

Outline
The changing process for developing technical documentation
Trends that are bringing changes
Web 2.0
Agile
Challenges and solutions
Where do we go from here?

Let’s collaborate….
Twitter: #stc10 or #pmcollab
My blog: http://bit.ly/bsE2PH

The Traditional Process
Long development cycles
Static “official” documentation products
Gathering content
Writers sometimes isolated from product developers
Write/Review /Edit/R epeat… then Publish

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

The Process: 30 Years Ago

The Process: 10 Years Ago

The Process: Today

The New Traditional Process
Short long development cycles
Dynamic, community-sourced Static “official” documentation products
Collaborative Gathering content
Writers must be in close touch with sometimes isolated from product developers
Write/Review/ Publish /Edit /Repeat

Trends that are Changing the Process
Web 2.0 (and beyond): New, varied sources for content How can I keep track of—much less control—the flow of content?
Agile methodology: “Just in time” development Hey, what does that do to my doc plan?

Web 1.0, 2.0, 3.0
Web 1.0: One-way information flow
Static publishing
No interaction
Web 2.0: From publishing to participation
Information sharing and collaboration
User-generated content
The community
Web 3.0: Marketing buzzword, or unrealized vision?
“ Intelligent Web 2.0”
Semantic Web, personalization, intelligent search, mobility
(Source: J. Leigh Brown and Peg Mulligan)

Web 2.0 and Publishing
From publishing to participation
Doc sprints, FLOSS manuals
User-generated content augments and even supplants the “official” documentation
The concept of the community

Example: Adobe Community Help

If you build it, they won’t just come
You have to
Invite participation
Make it easy
Give prominence to UGC

You need a content strategy
Creating content
Delivering content
Governing content

The Content Strategist
“ Curator” – not “gatekeeper”
Keeps the big picture in mind
Manages content throughout the content lifecycle
Enforces a strategy that’s repeatable

The Agile Manifesto
We value:
Individuals and interactions over processes and tools
Working software over comprehensive documentation
Customer collaboration over contract negotiation
Responding to change over following a plan
That is, while there is value in the items on the right… ….We value the items on the left more.

An Agile documentation project
Small, tightly knit teams
Scrums
Writers have to be fully involved
Modular writing
Focused on major needs of the user
Topic based

User stories
They drive the product and the docs
Basis for your audience analysis
Short development cycles
Sprints
Geared to being flexible
How quickly can you publish?

The doc plan is subsumed by the content strategy

Principles for Writing in Agile
From Anne Gentle’s Just Write Click blog
Only deliver things that an actual customer would find useful.
List and prioritize all tasks that get you incrementally closer to your goals.
Understand the business goals. Ask questions and seek details.
Deliver something that the team considers to be done, shippable, and customer- ready .

New wine into old wineskins?
No.
New wine into new wineskins.
(St. Mark 2:22)

Web 2.0 and Agile Challenges and Solutions

Web 2.0 and Agile: Challenges
Reviews are often ad hoc and very limited in scope
How to edit
What to do with legacy information
How to plan for localization/translation

Challenge: Reviews
Very few SMEs involved
Hard to squeeze into the iteration schedule
Topic-based reviews don’t provide the big picture

Solutions: Reviews
Make sure that Tech Pubs is a full member of the team
Find a champion
Conduct targeted reviews
You might need a special “big picture” review
Keep track

Challenge: Editing
Editing can’t be a one-time event
A comprehensive edit isn’t possible
Writing teams might not know each other – or the editors
Content comes from nontraditional sources

Solutions: Editing
Editing as an ongoing process
Topic-based editing
The editor is still part of the team – working closely with PM and content strategist
Style guides are vital

Challenge: Legacy Content
Easy to overlook in sprint-based reviews
Reviewers don’t see new and changed content in context
Scrum team members don’t have time to review old content

Solutions: Legacy Content
Don’t skip the content inventory!
Content is best reviewed by an experienced SME
Review can be done at any time
Help the SME by laying out the ground rules

Challenge: Localization
Scheduling translation
Handling changes to the product content

Solutions: Localization
Break the translation into pieces
Align the translation schedule with your iterations
Take advantage of the processes your software developers are following

Evolving a set of best practices
We’re still learning
Let’s share the things we learn
What new trends are coming?

Resources
Bailie, Rahel: “Rahel Bailie Provides A Content Strategy Primer,” Sept. 2009 (article at http://thecontentwrangler.com)
Gentle, Anne: Conversation and Community: The Social Web for Documentation
Halvorson, Kristina: Content Strategy for the Web
Hamilton, Richard: Managing Writers: A Real World Guide to Managing Technical Documentation
Sheffield, Richard: The Web Content Strategist's Bible: The Complete Guide To a New and Lucrative Career for Writers of All Kinds

Your turn Q & A

Managing Documentation Projects in a Collaborative World

by Larry Kunz on May 06, 2010

Accessibility

Categories

Tags

Upload Details

Usage Rights

1 Embed 17

Statistics

Managing Documentation Projects in a Collaborative World — Presentation Transcript