An Agile review process for documentation

Documentation teams need a fast and effective review process to move forward on their projects and deliver quality, timely content. Reviewers, may they be SMEs (Subject Matter Experts) or key organization authorities, are usually extremely busy and have limited time (or interest) to review documentation. Interesting dilemma, no?

To move away from this LOSE-LOSE situation, we designed our LiveTechDocs review process with simplicity, transparency, and efficiency in mind. Let me walk you through the building blocks.

The actors

We define three key actors with well-defined responsibilities in this process:

1. Reviewers: post documentation feedback (comments) directly on LiveTechDocs projects
2. Technical Writers: modify the documentation based on existing comments
3. Project Managers: manage the review process; ensure all issues are fixed correctly; track progress

The process

The LiveTechDocs review process enables a transparent discussion between these actors. In a nutshell, the following features are exposed in documentation projects:

• the documentation is divided in logical blocks of content (ex.: title, paragraph, bullet list, image)
• discussion threads are created by posting a comment on the content block
• users can interact in several ways (depending on their role): post a reply, set the comment to "fixed", or archive it
• icons on the right-hand side of blocks indicate the thread status:
  • No comment
  • One new comment
  • Comment(s) fixed
  • Comment(s) archived

Example

Here's an example of the process:

• A reviewer thinks that a section title "Product information" should be renamed "Product Overview". He posts a new comment.
• The comment is assigned to the technical writer in charge of this chapter.
• The technical writer updates the XML source file with the new title, uploads the new file in the "Repository", republishes the documentation, and sets the comment status to "Fixed".
• The reviewer is notified of the correction and the comment is assigned to the project manager.
• The project manager validates the correction and if satisfied, closes this thread.

What happens if the reviewer disagrees with the fix? He simply posts a reply on the same thread and notifies both the technical writer and project manager. If the comment already has been "archived" by the project manager, he re-opens it and assigns it back to the technical writer.

Conclusion

The LiveTechDocs review process provides several benefits to the key players in this process:

1. The reviewer's job is simplified.
2. Technical writers do not manually map comments to the XML documentation.
3. The project manager is aware of the review status at any time and can take action quickly.

Once your teams become familiar with our transparent review process, you will experience faster review cycles delivering better results.

As usual, if you have questions or remarks, post a comment on the blog. Your opinion is important to us!

Fabrice Talbot
www.livetechdocs.com