by Serguey Shinder
For years I reviewed design documents the way most of my colleagues did. The link would arrive, I would open it, and the document would already be covered in other people's comments down the right hand side. I read the text and the threads together, replied where I had something to add, resolved the small things, and moved on. It felt efficient. It felt collaborative.
In the autumn of 2024 we reviewed a proposal to change how stock reservations work between our website and our branches. Eleven pages, six reviewers, fifty eight comments. It was approved. Four months after it went live we found that, under one particular sequence of events, the website and a branch could both reserve the last unit of the same item, because the design had them each keeping their own count and reconciling every few minutes. The proposal said this plainly on page nine.
Nobody had commented on page nine. When I went back and counted, forty nine of the fifty eight comments were on the first three pages: naming, the wording of the goals, a diagram somebody thought was confusing. I had written six of those comments myself. I had read page nine, technically. I could not have told you what it said.
The comments had not merely distracted me. They had steered me. Each one was a small conversation with a person in it, and a conversation is far more interesting to a tired reader than a paragraph about reconciliation intervals. The early reviewers commented on what they met first. Later reviewers read those comments and responded to them, and by the time anybody reached the hard part of the document, their attention had already been spent where everybody else's had been spent.
So I review in two passes now, and the first one is alone. I read a clean copy with every comment hidden, in one sitting, and for longer documents I print it and take it away from the desk, because the paper has no notifications and no threads. I write nothing in the document during that first pass. I make notes on paper, and at the end I write down the two or three things I think matter most before I look at anybody else's view. Only then do I open the comments, and I add mine.
When I write a proposal myself, I now say at the top which section I am least sure about and ask reviewers to start there.
My comments are fewer than they used to be, and they are more often about something that would hurt. What changed was not my concentration. It was that I stopped letting the first person to comment decide where everyone else would look.
– Serguey Asael Shinder
Leave a Reply