Tag: <span>Seth Godin</span>

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.