May 26, 2009

Managing the Documentation Review Processs with Surround SCM

Surround SCM
The developers at Seapine have been using the Surround SCM workflow to manage code reviews ever since that feature was released in version 5 (back in 2006). Earlier this year, I decided to start using the Surround workflow to manage documentation file reviews, instead of using TestTrack. Why? A couple reasons, but the biggest one being that we store our source files in Surround SCM. Since the technical writers are used to checking their work in/out of Surround, using the workflow seemed like the logical next step. We generally only use the workflow for release-related documentation, when turnaround time can be important and the technical writers each have a few guides (and related documentation files) to work on. The workflow keeps us all on the same page and cuts down on confusion. In addition to creating workflow states, we also had to create a few triggers in Surround SCM. Following are descriptions of the workflow states and triggers. Workflow states and triggers
  • Work in Progress - Initial workflow state for files that are part of the review process.
  • Needs Review - When technical writers are ready for files to be reviewed, they move them to this state. After a file moves into this state, a trigger that sends me a notification email runs.
  • Needs Attention - If files need changes based on edits/reviews, they are moved to this state. After a file moves into this state, a trigger that sends the technical writers a notification email runs.
  • In Revision - After the changes are made to files, they are moved to this state. It's like an intermediate Needs Attention state. As long as changes are needed, the file stays in this state.
  • Passed Review - Files that do not need any changes are moved to this state. If a new version is checked in, a triggers that automatically moves the file back to the Work in Progress state runs.
We have a small documentation team at Seapine, but I believe this simple workflow could be easily adapted for any size team and most any review/edit/revise process. Contact me if you have questions or would like more information.