Criminal Intent

I review a lot of documents.

What those documents are is unimportant to this blog post, as it is the act of reviewing that I want to talk about.

Said act follows a consistent loop:

Read. Understand. Evaluate. Repeat.

The tricky part is sharing the feedback generated from that loop.

What Are You Doing?

Reviewing a document is hard work, both for the reviewer and for the author.

The reviewer has to read a bunch of stuff, interpret it, understand it and synthesize that understanding into some sort of meaningful action. Perhaps the document is fine as it is, and the action is just acceptance, or perhaps it could be improved, in which case the action becomes the generation and communication of feedback.

The author has it just as hard. Not only did they have to do all the work to create the document, but they also then have to put it out there to be critiqued. Having something you've worked on be questioned and evaluated can be emotionally difficult to deal with and then you have to actually do something with the resulting feedback.

Which can be a journey unto itself.

When you get feedback on a document that you've created, it doesn't always come with enough context to understand the intent behind it. Especially if the feedback is coming asynchronously.

• Is it an issue that must be fixed or the document is vastly less effective at its intended purpose?
• Is the feedback merely a partially formed thought, meant to inspire similar contemplation?
• Is it praise, congratulating the writer on really nailing some particular element?
• Is it something else entirely?

Interpreting the feedback, understanding the intent, and then determining the correct action to take can be almost as challenging as writing the document in the first place.

But it doesn't have to be.

I'm Just Underlining The Dirty Parts

In most software engineering teams, the act of reviewing code is typically done via a pull request (or PR).

While not exactly the same as reviewing a document, the goal is similar; to critically evaluate the change or submission and to then provide feedback to make it better, for whatever better means in context.

The process of reviewing a PR is similar enough to reviewing a document that the process of giving feedback can suffer from the same problem; missing or difficult to interpret intent.

The good news is that someone has already come up with a way to resolve that problem for PR's, which means we can just steal it wholesale and apply it to document reviews.

Enter Conventional Comments.

The goal of conventional comments is very simple: clearly state your intent whenever you make a comment.

I'm not going to copy the linked page wholesale, because it does a great job of explaining itself. I will, however, extract a few pertinent labels to whet your whistle and encourage you to go read that page in more detail.

Labelling a comment as [issue] indicates that there is something wrong that should be fixed. This label should be accompanied by a [suggestion], to help the author of the document deal with the issue.

[issue] This section does not actually tell the truth. The success measures that we were using for the project are incorrect, as the measures shown here were for the subproject.

[suggestion] Update the success measures to be the ones we were using for the project, and include the subproject measures for context, to indicate that we considered multiple dimensions when measuring success.

Labelling a comment as [praise] indicates that you want to appreciate a job well done. There is no action necessary other than feeling good.

[praise] This chart is excellent! It clearly shows the ramifications of the changes that you will make to the system and makes it easy for me to decide if the trade-off is worth it.

Labelling a comment as [nit] indicates that you think there is room for improvement, but the improvement feels more like a personal preference or is unimportant in the overarching scheme of things. This is good for when you have something to say, but you aren't attached to the resulting action. The author is free to ignore or apply the feedback, it's up to them.

[nit] I don't like that you've spelt behaviour incorrectly here.

Finally, labelling a comment as [thought] indicates that you have a thought but don't know what to do with it. The section that you are commenting on inspired some sort of mental process, and it might be worth a discussion, or it might not. The expected action here is to engage with the thought and draw it out, to see where it leads.

[thought] What if we took design #2 and combined it with design #3? Would we be able to get the best of both worlds?

Pretty useful, right?

Try To Curb Your Enthusiasm

My team started using Conventional Comments months ago when they identified that PR's were becoming a pain point. It seemed like a pretty good idea, but I don't write or review code, so I didn't really think about it all that much.

It's only relatively recently that I've started applying it to document reviews, but I can already see the value. I've already noticed an improvement to the quality of the feedback that I'm giving and a commensurate improvement to the final quality of the documents afterwards, with less back and forth required.

By labelling your comments with an intent, not only are you giving the author of the document more context to work with, you force yourself to think about the comments that you're making in more detail. There have been a few times when I was going to make a comment on a document, but through the process of thinking about my intent, I realised it didn't actually help at all.

Anything that clarifies your thought process and reduces superfluous noise generated is to be treasured.

It also helps to set expectations with the author, increasing the chances that the comments will be taken into account and the resulting document improved. Something marked as an [issue] with a [suggestion] for how to deal with it is far more likely to be actioned than a vague comment stating that a section isn't good enough.

There are, as always, costs incurred for these benefits though.

Consistently labelling your comments with an intent requires discipline. This is important mostly when you're getting started, before the habit is formed, and you have to consciously use willpower to remind yourself to do the thing. It's easy to just swoop down on a document, crap a bunch of comments and then flap away like some sort of demented eagle, but you need to be better than that.

Adhering to the pattern of labelling your comments with intent also takes more effort overall. You need to think about your comments more, clarifying them in your head, before you can communicate in a more structured fashion. That means the document will take longer to review, which might be an issue depending on how time poor you are. Be aware of the trade-off that you are making (quality over speed) and account for it appropriately.

I'm Pretty Good At Connecting The Dots

As a primarily remote worker, the way that I interact with my colleagues is becoming more and more asynchronous. This can bring all sorts of benefits, but it does make communicating intent even more important.

In an asynchronous world, you can't always get real-time clarification on whatever is being discussed, so being able to understand the message in isolation becomes necessary to maintain momentum.

Using Conventional Comments is just one way that you can provide extra clarity in your feedback when reviewing documents. A little bit of effort on your part as the reviewer can keep things moving and make everyone's lives just a little bit easier.

Seems like a worthy investment to me.