Documentation is the castor oil of programming. The managers know it must be good, because programmers hate it so much. Gerald M. Weinberg
I used to be a strong believer in formal doc reviews. Distribute a draft, plan a meeting, and have everyone gather around the table. But in the last few years, my team has moved towards mostly meetingless reviews–because people hate review meetings (you know, like code reviews, only worse), because people haven’t always read the drafts when they get to the meeting, and because some of our dev team is overseas.
- First, we distributed PDFs and asked reviewers to submit comments in email or on a hard copy. For the overseas team, email was the only option. This is not fun for either the reviewer, who has to do a lot of copying and pasting and referring to page numbers, or for the writer.
- Then we tried Adobe Acrobat PDF reviews, which allowed all reviewers to comment on the same PDF and view others’ comments. This was a big improvement over the email method.
- Now that all of our product documentation is hosted on a MediaWiki-based site, we’ve asked reviewers to edit the pages themselves, or add comments to the Talk pages. This makes life much easier for both reviewers and writers.
How do we encourage developers and testers to “own” the documentation for their tools, and to think of help as part of the product? If we can get developers and testers to RTFM, the benefits are obvious. They understand the tools in a way that no one else does, so they’ll provide feedback that no one else can. And they’ll become familiar with the help for the tools they’re responsible for, so they’d know whether a change they’re making or testing would affect the help.
I thought up a few ways that might increase the amount of review feedback:
- Create review tasks in our Agile project tracking tool, XPlanner. A top-down approach, and I wasn’t enthusiastic about it. Kinda like the daily castor oil treatment.
- Make everyone’s MediaWiki user page into their doc review page; we’d add links to these pages and reviewers would be notified through email, then they could delete the link when they’ve reviewed it. A nice bottom-up approach, I thought, in the spirit of the wiki.
But encouraging collaboration may be less about tools and more about process. If we involve reviewers earlier, they can tell us what they think before we’ve written a draft. A draft takes a long time to review, and if a reviewer doesn’t like it, they might not provide any feedback at all.
Documentation isn’t bad. But bad documentation is terrible.
Is reviewing docs worse than eating Brussels sprouts? Do you review docs when asked, or do you hide the invitations under the edge of your plate, hoping mom won’t notice? Is the help so bad that you can’t be bothered? Are you just too busy? Are you one of those people who never consults the help for tools you use? Do you think your users will be able to use the tools you’re developing or testing without the docs?
What would make you more inclined to “own” the help for the tools you’re developing or testing?