Notes from 57th International STC Conference
Dallas, Texas, May 2-5, 2010

Managing Documentation Projects in a Collaborative World

Larry Kunz

Documentation project manager for Systems Documentation, Inc., with 30 years’ experience. Also an STC leader at the international level.

Session Description: Two trends, community-based authoring and Agile, are revamping management of documentation projects. Fortunately, these trends share much in common. Content strategy emerges as an important new discipline.

• Outline
   
• Changing process for developing tech doc
• Trends
• Web 2.0
• Agile
• Challenges and solutions
• Where do we go from here?
• #pmcollab... Twitter follow-up
• Blog: http://bit.ly/bsE2PH
• Traditional process
   
• Static “official” documentation products
• Gathering conten
t
• Writers sometimes isolated from product developers
• Write/review/edit/repeat/publish... this is the core of the process and it has not changed, but the media have
• The Doc Plan: “It is the star to every wandering bark...” Sonnet 116 (Shakespeare)
• How do Agile and Web 2.0 (dynamic) conform to a doc plan (static)?
• Through the 1990’s and 2000’s, new deliverables supplemented or replaced traditional paper docs: online (DVD), web-based documentation
• Today’s process is a two-way street, with input not just from SMEs but also from customers (Twitter, Facebook, blogs, wikis, etc.). Documentation is maintained and updated in real time
• New process
   
• Short development cycles (“sprints”; partial releases)
• Dynamic, community-sourced documentation products
• Collaborative content (rather than “hunting and gathering” from SMEs); more interaction
• Writers must be in close touch with product developers (fully integrated with the team from the start)
• Write/review/publish/edit/repeat... sometimes the edit step is omitted (heresy!) or done after a segment has already been released online.
• Web 2.0
   
• 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?
• What’s the new doc plan? It’s the content strategy.
• 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
• 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 (all stakeholders: SMEs, writers, users). Adobe Community Help is a good example of that... a mix of official Adobe documentation and feedback from the user forum.
• How do you handle raw user feedback (might need editing, might be very negative) and still provide a near-real-time forum? Publish with a very “coarse” filter to avoid truly objectionable material from being posted; with the rest, include a caveat to the effect of “This is user-generated content that has not yet been explored or validated by Adobe.”
• If you build it, they won’t just come. You have to:
   
• Invite participation
• Make it easy
• Give prominence to UGC (user-generated content
)
• You need a content strategy
   
• Creating content
• Delivering content
• Governing content
• What is content strategy? A repeatable system that governs the management of content throughout the entire content life cycle.
   
• Content strategy begins with a content inventory.
• Content strategy has created a new function: “content strategist”
   
• “Curator,” not a “gatekeeper”
• Keeps the big picture in mind
• Manages content through the content life cycle
• Enforces a strategy that is repeatable
• The Agile Manifesto. We value:
   
• Individuals and interactions over processes and tools (goes against traditional project manager’s mind set)
• Working software and docs 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 (daily meetings; term comes from rugby: a “free-for-all”; no set agenda)
• 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?
• An Agile documentation project: The doc plan is subsumed by the content strategy.
• Principles for writing in Agile
   
• 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.
• Challenges and solutions
   
• 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
• Reviews
  
  Challenges
   
• Very few SME’s involved
• Hard to squeeze into the process
• Massive amount of material to review
Solutions
 
• Make sure tech pubs is a full member of the team
• Find a champion
• Conduct targeted reviews
• You might need a special “big pic” review
• Keep track
• Editing
  
  Challenges
   
• 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
Solutions
 
• Editing as an ongoing process
• Topic-=based editing
• Editor is an integral part of team, interfacing with SMEs, users, marketing, etc.
• Style guides are vital
• Legacy content
  
  Challenges
   
• 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
 
• 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
• Localization
  
  Challenges
   
• Scheduling translation
• Handling changes to the product content
Solutions
 
• Break the translation into pieces
• Align the translation schedules 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?