The Levels of Review

Over the last year, I’ve been proud to be a member of the team over at Baeldung, editing articles with a variety of talented authors and fellow editors.

Reflecting on what I’ve learned from the experience, I think technical review has four tiers. It’s probably a good idea to focus the review on a tier at a time, as they’re cumulative. As discussed in code review consent, it’s also important that the reviewer relationship is correctly established/verified so that the review feels like a benefit to the author, rather than an argument/interference.

The tiers:

  • Suitability/ownership – is the author the right person to be producing the work, is it their responsibility? is it a fair thing to expect them to tackle? are they meant to be including collaborators?
  • Goals and narrative – what is this trying to achieve? and do we have a high level approach to getting from start to finish?
  • Content – does this work have the right number of the right things? essentially, there should be one of everything and everything in its place, much like the universal coding standard would recommend
  • Detail – at the microscopic level, is this clean of glitches and quirks? typos, minor bugs, stylistic improvements etc

While you may be able to spot issues in multiple tiers at a time, in my view, it’s kindest to put the focus on the tiers in order through the lifecycle of constructing and cultivating the work.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s