Sorry about being so late folks. That's my (Matt) fault not Valerie's.
Getting Useful Reviews
In this chapter, Barker describes the method of producing and obtaining quality reviews of any document.Barker describes Guidelines for Managing Documents Reviews
- Review the document objectives from the documentation plan
- Determine the type of review needed
- Establish a review schedule
- Plan the reviews
- Write a cover letter with questions for reviewers
- Prepare feedback material for reviewers
Review the document objectives from the document plan:
Review the document plan to find what aspects of the document you would like reviewed. For instance, the document provides task-oriented examples of processed images, ask the reviewer if the examples reflect real-world tasks.Determine the type of review needed:
- User reviews: Reviews by the actual intended users of the document.
- Management reviews: Reviews by managers and supervisors associated with your documentation project.
- Technical reviews: Reviews by programmers and developers of the software.
- Client reviews: Reviews by the people or department paying for the software and documentation.
- Subject-matter expert reviews: Reviews by experts in the professional field represented in the software.
Establish a Review Schedule:
Sequential Circulation involves making one copy and passing it from person to person.Pros:
- Low cost
- Less hassle
- Encourages team spirit
- Spawns arguments in the margin
- Early reviewers affect later reviewers
- Causes political problems (who gets it first and who gets it last)
- Hard to control
- Takes extra time
Simultaneous Circulation involves making a copy for each reviewer.
Pros:
- Fast
- Good for geographically diverse reviewers
- Fosters a one-on-one relationship
- Easy to control
- Easy, when online
- Expensive
- Takes more of your time
- Fosters redundant comments
- Causes version mix-ups with online
Plan your reviews:
Writing up a strategy and a schedule for the review will help it to go smoothly and be more productiveWrite a cover letter with questions for the reviewers:
- Indicate document objectives and benefits to the reviewer
- Ask for specific advice/comments
- Provide the necessary background
- Tell reviewers how to mark or comment
- Give dates and places for return
- Thank your reviewers
2 comments:
I think it can sometimes be really challenging having a useful review process that incorporates the opinions of users. You would think that the end users would be in the best position to judge the effectiveness of a piece of documentation, but depending on the nature of the project, I've found that this often isn't the case. The users may have a great deal of knowledge on the subject matter, but lack the communication skills necessary to effectively critique a document. They might also be so close to the subject matter that they can not view it with objectivity and a big picture focus.
My comment for this chapter doesn't exactly deal with technical documentation, but it's about some of my experience with reviews. At my job, I was given the task of observing a fellow worker, and then I was to give them a written review of what I had seen. The directions I was given for the process didn't really make any sense, and it would have been nice to receive a cover letter with some sort of direction for the observation. I kind of made my own techniques for the observation, and my review was based on those criteria. I don't think my coworker received a sufficient review because as the reviewer, I wasn't given adequate direction. It taught me that if I'm expecting people to review something for me, including documentation, I'd better give them clearly explained directions if I want a review that actually means something.
Post a Comment