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 ContentThe 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.
Part 2: The Use of Agile Methodology in User-Generated ContentThe 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.
Part 3: Agile Processes and MindsetThe 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.
Part 4: Features for a Tool to be Useful in this ContextThe 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.