?

Log in

Documentation Reviews in distributed teams (or Get your Reviewers a Cool Photocopier) - Adam Goucher [entries|archive|friends|userinfo]
Adam Goucher

[ website | My Website ]
[ userinfo | livejournal userinfo ]
[ archive | journal archive ]

Documentation Reviews in distributed teams (or Get your Reviewers a Cool Photocopier) [Mar. 2nd, 2006|08:12 pm]
Adam Goucher
[Tags|]

Reviewing documentation for accuracy and completeness is one of the necessary evils of testing a product. These days, documentation is typically delivered as a PDF rather than paper (and if print copies are even available they tend to be an extra cost). The problem with electronic formats is how to do you communicate issues/changes.

  • A bug with a long list of things to change

    • Pro: provides an easy checklist to change and verify against

    • Pro: don't have to read a 200 page document entirely on a computer screen

    • Con: these bugs can be large and ping-pong between Test and Doc as they change bits of the bug but not the whole thing


  • A bug with an electronically marked up version of the doc

    • Pro: provides quick context for all changes

    • Con: every tester must have the correct software to edit the file

    • Con: have to read a 200 page document entirely on a computer screen


  • A bug with a scanned copy of a a marked up version of the doc

    • Pro: provides quick context for all changes

    • Pro: don't have to read a 200 page document entirely on a computer screen

    • Con: need a Cool Scanner*




As the title sorta gives away, I'm a (currently) a fan of the last method. And it works great when teams are geographically dispersed. The list of changes format falls on it's face as soon as a section is inserted or removed and the page references are all out of kilter and the doc writer cannot come over to your desk to clarify things. Throw time zones into the mix and you have email ping-pong. The mark-up the original electronic form requires everyone to have the same version of the editing tool, and in some formats in-line editing might not be feasible or practical. Printing and marking-up the original copy retains the context on the comment as it is on/around the physical area in the document and by scanning what you are essentially doing is dropping the marked-up version on the doc writer's desk -- even if their desk is on the other side of the continent or ocean. And you can both have conversations about 'what did you mean by..' a month later and you, the original submitter, have a much better chance of remembering as you can open the scanned version up and be looking at the same thing.

* Our photocopier will scan a document and email it to you as a pdf. This is hella cool. I can print out the sections I care about of a document, scribble, cross-out and generally mark the heck out of it (with my red editing marker), then run it through the feeder and have something to attach to a bug submission. I only wish it could scan duplex through the feeder so I could print things out duplex. And yes, I recycle the marked-up copy which mitigates the 'but you are killing the innocent trees' argument to some degree)
linkReply

Comments:
From: (Anonymous)
2006-06-25 05:58 pm (UTC)

Reviews

Hello
I have cited you in my favorites.
I hope you would reciprocate
Best, Mohamed
http://mtindias.blogspot.com/
(Reply) (Thread)