Documentation review – Get it done!
- By Fabrice Talbot
We had the pleasure of giving a workshop called "Documentation review - Get it done!" at the local San Francisco STC chapter earlier this week. We designed this workshop around three interactive games played in groups. We wanted to make the evening an enjoyable learning experience for everyone. Those games helped participants identify key fallacies experienced during documentation review and the best way to address them.
Game #1 - Tops & Flops
We asked participants to share their best and worst documentation review story inside their group and to come up with their best Tops & Flops. The feedback revolved around three key themes
- Team collaboration: Everyone had an horror story about the difficulty to get feedback from reviewers; the lack of a collaborative environment made the review nearly impossible; some users cited successful experiences implementing a "war room" review (all in a room to do the review) however required that all reviewers had first completed a personal review of the document and second were physically in the area. All participants seemed to agree that asking for team commitment prior to starting the review process was helpful.
- Tools&Technology: While many writers used technologies such as XML and single-sourcing, it was clear that tools and technology used for sharing documentation and collecting feedback were below par. Among the top flops we listed: mutliple copies and formats sent for review; incorporating comments is time consuming; feedback is left out; hard to manage conflicting comments or duplicates. There weren't many solutions proposed; some mentioned letting reviewers edit directly in the source XML file or using color coded pens on a single hard copy.
- Review process: Unstructured review, conflicting and duplicates comments, feedback on grammar and sentence structure, and how to handle feedback were among the main flops; however some participants shared interesting processes related to their tops, such as identifying SMA (Subject Matter Areas), assigning SMA to SME (Subject Matter Experts), and organizing a review kick-off (roles, planning, progress tracking).
Game #2 - Version Madness
We played two short games and asked each group to perform a documentation review. In the first game, the writer distributed one document to every reviewer and asked them to provide feedback in two minutes; in the second game, the writer was asked to collect the reviewers' feedback based on a single version of the documentation.
Giving one version of the document to each reviewers created many problems: conflicting comments, duplicates, and the need to merge all comments into one document. When one version was used for review, participants experienced a better collaborative experience and agreed on what needed to be changed. However, a few expressed concerns over the lack of a leader to manage that process and how time consuming the review became.
Game #3 - Open vs. Structured collaboration
This game was also split in two parts. First we asked everyone in the group to take a copy of the document and review it. Then we named a group manager, distributed a black and red color-coded documentation for review and asked the manager to organize the review.
Generally, users involved in the "wiki-like" review (first part) recognized the benefits of being involved and make themselves heard; however they also pointed out that this feedback approach was time consuming, generated conflicting comments, and duplicates. While not everybody understood right-away the structured collaboration process (second part), participants usually agreed that clear directions improved their productivity and led to less comments to process and quality feedback.
The games were designed to put in evidence some of the best and worst documentation review practices.
#1 - Tops & Flops
- Doc review is at its best when the team is engaged
- Effective doc review is achieved with the right tools
- Doc review requires a clear process
#2 - Version Madness
- Collaboration fails when people work on separate medium
- Reviewing time is reduced by working on a central document
#3 - Open vs. Structured collaboration
- Reviewing docs requires a structured workflow and defined roles
- Open collaboration works better for crowd sourcing than project management
Do you agree with our "Tops" or "Flops"? Send us yours. Join the debate, drop a comment!