[Show/Hide Right Column]

Managing Documentation Projects in a Collaborative World

In keeping with our promise to provide an article on watercooler chats  , here is a summary article of the last watercooler chat, which was a four-part series on "Managing Documentation Projects in a Collaborative World — New Best Practices for Editors." The chat series was held between January and February, 2011 and was moderated by STC Fellow, Larry Kunz.

The chat series provided an interesting steam of ideas and wisdom based on the real-life experiences. However, the truth is that in this summary article it was a challenge to provide a coherent flow of thought because chats tend to meander and ideas do not always progress logically. Nevertheless, read on for the distilled wisdom:-)

Part 1: User-Generated Content

The first session on 21 Jan, 2011 focused on getting a perspective on user-generated content from the chat participants.

During the chat, it was mentioned that Wiki documentation is becoming more common, especially in certain user communities that expect a rapid-turnaround mode. And, one of the participants explained about wiki documentation in his workplace. In this specific case,
  • All members of the development team (tech writers, software developers, marketing, support, etc.) contribute directly to the wiki documents.
  • The wiki is public-readable. All content is "live" as soon as you click "save". Many pages (that are public) are clearly marked as "draft" or "in progress."
  • The development team even makes their feature scope documents public.
  • Here the technical communicator’s role is much more about managing and organizing content than actually *creating* content.
The chat participant indicated that all this fosters lots of end-user feedback! However, not everyone seemed comfortable with this approach. There was also a mention of the tradtional approach of getting user feedback through forms or surveys and using that to generate content.

Part 2: The Use of Agile Methodology in User-Generated Content

The second session on 28 Jan, 2011 focused on the use of agile methodology in user-generated content. A few of the participants used the agile methodology and provided perspectives based on their context, which are given below:
  • Editoral "passes" no longer occurred at (or near) the end of the cycle. It all happens at the same time, unfortunately usually out of context :(
  • This might also mean multiple "drops" of edits because of the many subsequent changes. Sometimes writers find it hard to write at all.
  • The alpha edit tends to be really organizational (for new documents). You can get a broad overview of the product workflow and make sure the document is clearly organized. You can also provide some writing reminders for the author to note as they work on the next iteration. It's a lot less work than performing one HUGE edit. Not only would that take forever but it would be frustrating for all involved.
It seemed like the use of agile methodology required a CMS, and it also emerged that DITA (topic-based writing) would fit well in this context. One of the chat participants expressed,” I love agile and (topic-based writing)! It forces everyone to plan rather than be reactive and make changes willy-nilly.” There were some thoughts expressed on the level of edit that is possible in a single pass as well.

Part 3: Agile Processes and Mindset

The third session on 4 Feb, 2011 focused on what does and does not work as people change their editing workflows for user-generated content and agile methodology. During this chat,
  • One participant indicated that daily stand-ups as well as sprint-planning meetings were part of the document development effort. They also tracked all stories and tasks in Team Foundation Server.
  • Another participant explained that they had weekly meetings, but they also have a "live" wiki doc that is updated, as needed and pretty much relects the "real thing." The weekly meetings are really only to talk about problems — not status. Problems or impediments get solved (or at least discussed) on a daily basis. If impediments go on for too long, then the product owner and manager deal with it at a higher level. There was a lot of accountability in this workflow.
Also, it seems like there are very short editing turnarounds and levels of edit also could become very important in this context. Those folks who don't cooperate become a bigger problem and you have to create a more severe way to deal with them (in all areas, not just editing, but certainly editing), and you have to learn to let go of projects. Also, probably LOTS of automation helps. It seems like style guides are useful if folks adhere to them, however there was also a perspective expressed that scripting could correct those terminology errors that are well-known or followed a pattern.

Part 4: Features for a Tool to be Useful in this Context

The fourth session on 11 Feb, 2011 focused on the types of features that a tool should have to be useful in this context. Participants expressed that should,
  • Collect input in a format that's easy to integrate with other content, BUT in such a way that the contributors aren't constrained by formatting issues. That implies, revision history, diffing, etc.
  • Separate input from delivery, as well as provide an easy way to transition from input to delivery.
  • Be flexible enough to provide a selection of delivery options.
  • Support simultaneous collaboration where two people can work on the same file. (Also, in collaboration, because it implies a certain amount of simultaneity, it would be good to have a feature that allows good controlling of source documents. )
  • Store information in a database, not flat files so that queries to build deliverables can be done on-the-fly.
There was also a brief sharing of perspectives on specific tools.

Page last modified on Thursday, April 28, 2011 06:42:49pm EDT
The content on this page is licensed under the terms of the Copyright.
Comments powered by Disqus
Corrigo: The newsletter of the STC Technical Editing SIG

Rate this article:
This article also appears in the following collections:
Category: Skills

Alert Also available as a blog...