Doc reviews don't have to suck

Allison Reinheimer Moore -

I was recently chatting with a friend who was frustrated because they felt they were having the same conversations over and over with different team members, either out loud in 1:1 meetings or in comment threads in Google docs that would then disappear when resolved. They knew I spend much of my time writing or reviewing Google docs, and asked how we do it. I am delighted to have a useful answer.

(Shout out to MongoDB's program management organization for introducing me to a document review process that I'm now shamelessly adapting.)

From my perspective, the ideal approach to collaborating on and reviewing documents involves two key principles:

  • If you have questions about the document, leave a comment in the document. It is then the document owner's job to reply and address your feedback.
    • Questions on docs often highlight points that are unclear or confusing; the document owner can then make the update and reply to the comment thread saying, for example, "took a stab at clarifying point XYZ, let me know if that answers your question".
    • Summaries of discussions in comment threads should be persisted into the body of the document, making sure that the discussions that were had are preserved. Resolved Google docs comments are viewable, but the user experience is terrible. The discussions we have in comments can highlight the rationale for the approach we end up taking (and the approaches we choose against). Capturing the approaches we did not choose and why they weren't chosen strengthens the document and ensures that a few years down the line, we can review and benefit from our past knowledge.
  • The person who initiated the comment thread is the person who resolves it. If there are multiple people in the thread, ideally they'll reply saying "I'm good to resolve if <original commenter> is," once the issue has been addressed, with ultimate 'click Resolve' responsibility staying with the original poster. This is hugely helpful for both commenter and document owner:
    • the person leaving the comment is empowered to ensure that their questions are satisfactorily addressed before the thread disappears.
    • the document owner has some insurance since the folks with questions/comments/issues have actively agreed the conversation is finished, thus preventing endless rehashing of past discussions.
    • It's clear whose job it is to click the [Resolve] button.

Project plans, product descriptions, requirement docs, tech specs, tech scopes, and design briefs are hugely helpful artifacts for development teams. If you can hash out what you're doing, why you're doing it, and what success looks like before you start building the thing, you reduce the likelihood of building the wrong thing or having to rework your approach when you're 75% of the way done… but that kind of consensus-building can also be time consuming and expensive if you don't have an established process to streamline it. It's even more expensive when team members keep re-hashing the same arguments, or you forget why you avoided some solution 2 years down the road.

When reviewing code, we have team conventions for pull request discussions and contributor guidelines in open source projects. Conventional Comments suggests pre-pending code review comments with contextual labels to further facilitate reviews and discussion. Adapting some of these approaches to our non-code reviews can be hugely helpful.

Ultimately, I've found that having discussion live in a Google doc (or, if a discussion has to happen in a meeting, having the outcomes of that discussion persisted to the doc) and requiring that the original commenter own the formal resolution of the discussion greatly reduces friction, builds consensus, and produces documents that have valuable context that can be reviewed years down the line.