managing documentation projects in a collaborative world technical communication summit may 2010...

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

Upload: leon-salmons

Post on 16-Dec-2015

234 views

Category:

Documents


1 download

TRANSCRIPT

Page 1: Managing Documentation Projects in a Collaborative World Technical Communication Summit May 2010 Larry Kunz lkunz@sdicorp.com  Twitter:

Managing Documentation Projectsin a Collaborative World

Technical Communication SummitMay 2010

Larry [email protected]: larry_kunz

Page 2: Managing Documentation Projects in a Collaborative World Technical Communication Summit May 2010 Larry Kunz lkunz@sdicorp.com  Twitter:

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?

Page 3: Managing Documentation Projects in a Collaborative World Technical Communication Summit May 2010 Larry Kunz lkunz@sdicorp.com  Twitter:

Let’s collaborate….

Twitter: #stc10 or #pmcollab

My blog: http://bit.ly/bsE2PH

Page 4: Managing Documentation Projects in a Collaborative World Technical Communication Summit May 2010 Larry Kunz lkunz@sdicorp.com  Twitter:

The Traditional Process

• Long development cycles• Static “official” documentation

products• Gathering content• Writers sometimes isolated from

product developers• Write/Review/Edit/Repeat…

then Publish

Page 5: Managing Documentation Projects in a Collaborative World Technical Communication Summit May 2010 Larry Kunz lkunz@sdicorp.com  Twitter:

The Doc Plan

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

Page 6: Managing Documentation Projects in a Collaborative World Technical Communication Summit May 2010 Larry Kunz lkunz@sdicorp.com  Twitter:

The Process: 30 Years Ago

Page 7: Managing Documentation Projects in a Collaborative World Technical Communication Summit May 2010 Larry Kunz lkunz@sdicorp.com  Twitter:

The Process: 10 Years Ago

Page 8: Managing Documentation Projects in a Collaborative World Technical Communication Summit May 2010 Larry Kunz lkunz@sdicorp.com  Twitter:

The Process: Today

Page 9: Managing Documentation Projects in a Collaborative World Technical Communication Summit May 2010 Larry Kunz lkunz@sdicorp.com  Twitter:

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

Page 10: Managing Documentation Projects in a Collaborative World Technical Communication Summit May 2010 Larry Kunz lkunz@sdicorp.com  Twitter:

Trends that are Changing the Process

• Web 2.0 (and beyond):New, varied sources for contentHow can I keep track of—much less control—the flow of content?

• Agile methodology:“Just in time” developmentHey, what does that do to my doc plan?

Page 11: Managing Documentation Projects in a Collaborative World Technical Communication Summit May 2010 Larry Kunz lkunz@sdicorp.com  Twitter:

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)

Page 12: Managing Documentation Projects in a Collaborative World Technical Communication Summit May 2010 Larry Kunz lkunz@sdicorp.com  Twitter:

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

Page 13: Managing Documentation Projects in a Collaborative World Technical Communication Summit May 2010 Larry Kunz lkunz@sdicorp.com  Twitter:

Web 2.0 and Publishing

Example: Adobe Community Help

Page 14: Managing Documentation Projects in a Collaborative World Technical Communication Summit May 2010 Larry Kunz lkunz@sdicorp.com  Twitter:

Web 2.0 and Publishing

• If you build it, they won’t just come

• You have to–Invite participation

–Make it easy

–Give prominence to UGC

Page 15: Managing Documentation Projects in a Collaborative World Technical Communication Summit May 2010 Larry Kunz lkunz@sdicorp.com  Twitter:

Web 2.0 and Publishing

• You need a content strategy–Creating content

–Delivering content

–Governing content

Page 16: Managing Documentation Projects in a Collaborative World Technical Communication Summit May 2010 Larry Kunz lkunz@sdicorp.com  Twitter:

The Content Strategist

• “Curator” – not “gatekeeper”

• Keeps the big picture in mind

• Manages content throughout the content lifecycle

• Enforces a strategy that’s repeatable

Page 17: Managing Documentation Projects in a Collaborative World Technical Communication Summit May 2010 Larry Kunz lkunz@sdicorp.com  Twitter:

The Agile ManifestoWe 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.

Page 18: Managing Documentation Projects in a Collaborative World Technical Communication Summit May 2010 Larry Kunz lkunz@sdicorp.com  Twitter:

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

Page 19: Managing Documentation Projects in a Collaborative World Technical Communication Summit May 2010 Larry Kunz lkunz@sdicorp.com  Twitter:

An Agile documentation project

• 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?

Page 20: Managing Documentation Projects in a Collaborative World Technical Communication Summit May 2010 Larry Kunz lkunz@sdicorp.com  Twitter:

An Agile documentation project

The doc plan is subsumed bythe content strategy

Page 21: Managing Documentation Projects in a Collaborative World Technical Communication Summit May 2010 Larry Kunz lkunz@sdicorp.com  Twitter:

Principles for Writing in AgileFrom 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.

Page 22: Managing Documentation Projects in a Collaborative World Technical Communication Summit May 2010 Larry Kunz lkunz@sdicorp.com  Twitter:

An Agile documentation project

New wine into old wineskins?

No.

New wine into new wineskins.

(St. Mark 2:22)

Page 23: Managing Documentation Projects in a Collaborative World Technical Communication Summit May 2010 Larry Kunz lkunz@sdicorp.com  Twitter:

Web 2.0 and Agile

Challengesand

Solutions

Page 24: Managing Documentation Projects in a Collaborative World Technical Communication Summit May 2010 Larry Kunz lkunz@sdicorp.com  Twitter:

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

Page 25: Managing Documentation Projects in a Collaborative World Technical Communication Summit May 2010 Larry Kunz lkunz@sdicorp.com  Twitter:

Challenge: Reviews

• Very few SMEs involved

• Hard to squeeze into the iteration schedule

• Topic-based reviews don’t provide the big picture

Page 26: Managing Documentation Projects in a Collaborative World Technical Communication Summit May 2010 Larry Kunz lkunz@sdicorp.com  Twitter:

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

Page 27: Managing Documentation Projects in a Collaborative World Technical Communication Summit May 2010 Larry Kunz lkunz@sdicorp.com  Twitter:

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

Page 28: Managing Documentation Projects in a Collaborative World Technical Communication Summit May 2010 Larry Kunz lkunz@sdicorp.com  Twitter:

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

Page 29: Managing Documentation Projects in a Collaborative World Technical Communication Summit May 2010 Larry Kunz lkunz@sdicorp.com  Twitter:

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

Page 30: Managing Documentation Projects in a Collaborative World Technical Communication Summit May 2010 Larry Kunz lkunz@sdicorp.com  Twitter:

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

Page 31: Managing Documentation Projects in a Collaborative World Technical Communication Summit May 2010 Larry Kunz lkunz@sdicorp.com  Twitter:

Challenge: Localization

• Scheduling translation

• Handling changes to the product content

Page 32: Managing Documentation Projects in a Collaborative World Technical Communication Summit May 2010 Larry Kunz lkunz@sdicorp.com  Twitter:

Solutions: Localization

• Break the translation into pieces

• Align the translation schedule with your iterations

• Take advantage of the processes your software developers are following

Page 33: Managing Documentation Projects in a Collaborative World Technical Communication Summit May 2010 Larry Kunz lkunz@sdicorp.com  Twitter:

Evolving a set of best practices

• We’re still learning

• Let’s share the things we learn

• What new trends are coming?

Page 34: Managing Documentation Projects in a Collaborative World Technical Communication Summit May 2010 Larry Kunz lkunz@sdicorp.com  Twitter:

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

Page 35: Managing Documentation Projects in a Collaborative World Technical Communication Summit May 2010 Larry Kunz lkunz@sdicorp.com  Twitter:

Your turn

Q & A