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.
- 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.