вход по аккаунту


Managing Documentation Projects in a Collaborative World

код для вставкиСкачать
Managing Documentation Projects
in a Collaborative World
Technical Communication Summit
May 2010
Larry Kunz
Twitter: larry_kunz
• 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:
The Traditional Process
• Long development cycles
• Static “official” documentation
• Gathering content
• Writers sometimes isolated from
product developers
• Write/Review/Edit/Repeat…
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
• 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”
• The concept of the community
Web 2.0 and Publishing
Example: Adobe Community Help
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
Web 2.0 and Publishing
• 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
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
–Writers have to be fully involved
• Modular writing
–Focused on major needs of the user
–Topic based
An Agile documentation project
• User stories
–They drive the product and the docs
–Basis for your audience analysis
• Short development cycles
–Geared to being flexible
–How quickly can you publish?
An Agile documentation project
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.
An Agile documentation project
New wine into old wineskins?
New wine into new wineskins.
(St. Mark 2:22)
Web 2.0 and Agile
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
Challenge: Reviews
• Very few SMEs involved
• Hard to squeeze into the iteration
• 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
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
• 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
Solutions: Localization
• Break the translation into pieces
• Align the translation schedule with
your iterations
• Take advantage of the processes
your software developers are
Evolving a set of best practices
• We’re still learning
• Let’s share the things we learn
• What new trends are coming?
• Bailie, Rahel: “Rahel Bailie Provides A Content
Strategy Primer,” Sept. 2009 (article at
• 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
Без категории
Размер файла
776 Кб
Пожаловаться на содержимое документа