Socialise Before You Write

Imagine you’ve spent months thinking about a problem. You write it all up into a document - full detail, carefully reasoned - and share it with the team. By the end of the first day it has thirty comments. Most of them are questions, and many of them are fundamental.

You’re frustrated. Your readers are frustrated. And the natural conclusion on both sides is that the other side isn’t doing their job - writers aren’t giving enough context; readers are being too picky.

The document probably isn’t the problem. The problem is that it’s the first time anyone else has seen the thinking and they’re trying to digest it all at once.

The Big PR Problem

You’ve probably worked with an engineer who disappears for three weeks and comes back with a 4,000 line pull request. It’s probably good code. It might even be the right solution. But now you have to reconstruct three weeks of their reasoning from the diff, and every decision they made along the way has disappeared into finished code.

Documents have the same failure mode. A full, detailed design or proposal that arrives out of the blue asks the reader to jump straight into the deep end of a problem they haven’t yet agreed exists. Every one of those thirty comments is really the same question: how did you get here?

The author knows how they got there - they’ve been living in it for months. But none of that is in the document, because to them it’s obvious.

Alignment Is Not a Document

Documents don’t create alignment. They record alignment that was created somewhere else - in conversations, in syncs, in hallway chats, in “hey, does this make sense to you?”

If you try to use the document to create the alignment, you will get thirty comments.

So the process is:

1. Name the problem out loud. In a sync, in a channel, in a 1:1. “I think we have a problem with X. Does anyone else see it?”
2. Collect opinions. Who agrees? Who doesn’t? What have people already tried? What do they think the first step is?
3. Write the smallest thing that captures the agreement. Problem (in three sentences, ideally), why now, overall approach, why that approach. Leave the specifics out - but if you considered an obvious alternative and rejected it, say so in a line. Someone else will have the same thought, and one sentence now saves you a week of comments later.
4. Get people to put their name on it. Not because you need permission, but because named agreement is how you find out whether you actually have it.
5. Then write the detail - if you still need to.

I’ve watched engineers take a problem that was annoying everyone but owned by nobody, and do exactly this: talk to colleagues, get a sense of the range of opinions and a sensible first step, start a short doc, rally people around it, and get it adopted as team practice.

That’s what technical leadership looks like. Not just a clever solution, but a well-socialised problem.

When You’re the Author

If you’re on the receiving end of the thirty-comment document, resist the urge to just answer the thirty comments. Step back. Thirty questions on day one is a signal that you are probably trying to use a document to create alignment that hasn’t already been created. That’s not a failure of authorship, it’s a failure of communication and collaboration. Someone (almost certainly you) didn’t create alignment before they tried to ask for it with a long-ass document.

The fix isn’t a better document. It’s conversation that should have happened earlier, and continuously.

So if you ever find yourself about to drop a big document - or a big PR - on people who’ve never heard of the problem, stop. Go and have the conversation first.

It’s faster, I promise.