What are you thinking when you review documentation?
We recently had a short discussion about how peer review, what we thought it was and how it should work. For us, having another member of the documentation team look over your work is useful for several reasons. Whilst we have distinct technical and editorial review stages, having another technical writer look over your work helps highlight things concerning structure, ordering and the killer of all killers, confusion.
Seth Godin nicely captured the reason why this is an important stage of information production:
If you’re building for digital, for a place where you can’t possibly be present to guide or to answer questions, I think it’s vital you have someone who can review your work … Not to make suggestions to make it better (what do they know?) but to share their confusions.
The thing is, it’s easy when you’ve been working on something for several weeks to get too close to the material and start making presumptions. These, inevitably, lead to confusion for the reader. It’s never an intentional thing, and everyone does it (and if they think they don’t, I’d suggest they may not be aware that they do!) but it’s something that we can easily catch.
The way we work, with each technical writer working on a distinct part of the product, it’s reasonable to assume that we can review a document without too much presumed knowledge. It’s not the same as handing the document to someone with no knowledge at all but we can usual spot those areas that may cause confusion.
Typically, these are the things that seem obvious when someone points them out, which a new customer will spot immediately because it leaves them perplexed. Unfortunately those are the moments when confidence in the content drops and, for many people, it only takes one or two instances of these for the documentation to be cast aside, never to be used again.
Catching points of confusion is a crucial part of any review process, it doesn’t really matter whether you have a specific process for it but it is something you should try and make sure you are addressing.
I agree that peer reviews are enormously valuable, and I try to get them whenever I can. But peer reviews also come with two big pitfalls to be aware of:
1. If you are writing task focused material, any review by a person who is not attempting to do the task is suspect. They are not reading for the right reason. (There is only one kind of person who reads technical documentation only to understand, and not to do, and that is a technical writer.)
2. If the writer who gives the review is not conversant in the area, they are apt to ask for clarifications of concepts that the real reader would be familiar with. Their requests for clarification could lead to bloat of the topic.
Review by your company’s field engineering staff avoids both these pitfalls. And we should not neglect the value of review by the customer either. We have the ability now to gather feedback from our customers and to update our docs to reflect that feedback. We should be making more use of it than we are.
Mark,
Thanks for your thoughts and, on the whole, I agree.
I think there is a presumption, from any kind of review, that review comments should be actioned. I disagree with that for the reasons you state above. Whilst I, if I’m not conversant in an area of the product, may call out an acronym, the writer should (rightly) ignore that if it is deemed common knowledge for the intended audience.
As for reviewing tasks, I’ve specifically suggested that, unless it’s a simple task, we should not review these as I’d assume they would be reviewed and corrected during the technical review. We work by using the software so this type of task error hardly happens.
Customer and field engineering staff are, of course, the best, but are expensive and time-constrained. We are looking at ways of closing that loop too.
Mark, I agree that peer reviews can be very useful in some circumstances. For example, confusion (as you mention) and accuracy.
Unfortunately, I have seen companies replace editors with peer reviewers. And this, in my opinion, can be a big waste of money and time. I think that technical writers should be reviewing “big picture” things, not style and grammar rules. But all too often, I see companies get rid of their editing staff, only to have their writers checking for style, grammar, and terminology. If you must eliminate editors (which I think is a bad idea), you should definitely get software that does all of your style-guide and custom terminology checking for you. That way, your peer reviewers are reading for the types things that software simply cannot catch. Taking a writing team away from writing to check for commas is a big waste (in my humble opinion).
Val,
Whilst I agree with the sentiment (we have a distinct separation of editorial vs peer vs technical reviews), I have yet to work in a technical writing team that had an editor.
Wondering if it has been down to the size of the teams? Or geographic preference?
I totally agree that technical writers should be reviewing “big picture” things, and that’s one of the areas I think we will need to check once we’ve been through a couple of peer review stages.