Mailbag: How to encourage good documents rather than perfect documents?

A great question on Staff Engineer that I received recently:

When you’re writing docs (and reviewing them) I really resonated with the idea of pushing for them to be good and not perfect. Was curious how you go about fostering that culture beyond yourself? I feel like since we’ve shifted to a remote culture, doc grooming has reached an all time high. Also curious if that’s something you’ve felt at all?

There’s an increasingly pervasive belief that written communication is the “obviously best” communication culture. This was initially driven by the cultural export of Amazon’s memo culture, and has been bolstered recently by tailwinds from the pandemic-driven shift to remote work. I’m quite partial to written communication, but it’s a challenging shift. This question hits on one way this shift can go awry: an emphasis on perfection rather than good slowing down discussions.

This is a fairly familiar problem for engineering teams. It comes up frequently in system design, in the tension between YAGNI and not wanting to rewrite the system in six months. Even more commonly, most engineers have been on a team where the perception of nit picking feedback during code review leads to only sharing pull requests for review after the approach has calcified beyond alteration.

The example of code review is probably the most familiar, so we can think about how the tactics for debugging a flailing code review process can be applied to writing culture:

1. People hide work because they’re uncomfortable. If documents are being shared late, it’s because some aspect of the sharing process is making authors uncomfortable. Usually this is because the feedback they’re receiving isn’t helping them accomplish their goal. Maybe there’s too much feedback and folks are waiting until late to share to minimize responses. Maybe the feedback isn’t useful, so folks don’t bother requesting feedback until they’re past the point of cheaply incorporating new ideas.
2. There’s probably four people at your company who make documents uncomfortable. Before you start thinking about a systems level solution to this problem, I’d guess that there are a very small number of people who need to be given direct coaching on how to provide feedback on documents. If you hold them accountable for how they engage with other folks documents, that conceivably might be enough to solve the entire problem.
3. Provide a structured template and document lifecycle. A flexible document template will eliminate debate on structural issues. A document lifecycle process will make it clear when to provide which kinds of feedback. The template and lifecycle act like a code linter in code review, moving feedback away from style and towards substance.
4. There’s a teachable skill to reviewing documents. If you ask someone to edit a document, a surprising number of folks will immediately gravitate to tweaking words or providing grammatical feedback. Sometimes this is useful, but it usually isn’t. While engineers tend to become better at code review with frequent repetition, most don’t do enough document review to get good at it. Fortunately, this is a teachable skill. Have folks read the entire document once before leaving any comments (avoiding the dreaded “but this is addressed later…” response). Focus feedback on the ideas rather than the format.
5. Provide a designated friendly reviewer / writing coach. Going further, most folks don’t have much experience writing documents either! You can reduce the perceived risk of sharing a document by providing a writing coach, probably an experienced engineer in their area, who can provide very early feedback. This coach will also be in a great position to nudge folks to ship their document when it’s “good enough” rather than continuing to polish it. This person also provide “social proof” for the person sharing the document, loaning their privilege as a senior engineer to the author that their document is indeed ready to share.
6. Provide a repository of “golden documents” with the right quality level. I bet you already have a list of “example documents” that folks should emulate, and I bet they are absolutely incredible documents. Which is to say, that they are absolutely not the example you want folks to follow if there is too much emphasis on perfection. Create a new list of “golden documents” which aren’t necessarily the best documents but instead those at the correct level of quality. Ideally you should even acknowledge the documents which are “too good.” Yes, they’re beautiful, but no, that’s not what we’re trying to do here.

Of all those things, I think the most effective approaches are continuing to model “good rather than perfect” behavior yourself, pushing other leaders to model that behavior as well, and lending your privilege for imperfection to authors who take a larger risk when publishing imperfect work.