Managing Documentation Projects in a Collaborative World
Upcoming SlideShare
Loading in...5

Managing Documentation Projects in a Collaborative World



Managing Documentation Projects in a Collaborative World

Managing Documentation Projects in a Collaborative World
Presentation at STC Summit: 4 May 2010



Total Views
Views on SlideShare
Embed Views



3 Embeds 24 17 6 1



Upload Details

Uploaded via as Microsoft PowerPoint

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
  • Great overview. Thanks for sharing!
    Are you sure you want to
    Your message goes here
Post Comment
Edit your comment

Managing Documentation Projects in a Collaborative World Managing Documentation Projects in a Collaborative World Presentation Transcript

  • Managing Documentation Projects in a Collaborative World Technical Communication Summit May 2010 Larry Kunz [email_address] 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:
  • 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
  • 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 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
  • 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?
  • 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?
    • 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
    • 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