Recently I was involved in a trial¹ of a form of collaborative feature definition that was, in a word, bad. It involved Miro (if you’re not familiar, think post-it notes), working from a single sentence (post-it) that loosely described a feature, with the hopeful end result being a ticket a developer could work on. Nothing was allowed into a real ticket until it made it through this process. All work on this process was done live on a call, with the entire team present.

Miro / post-its are a great tool, and collaboration is a great thing, but this was not it.

Post-it Driven Development

A post-it note length sentence being your only entryway into defining a piece of work meant that people would forget what they actually meant when they wrote it a month ago. Because they were just post-it notes on a board there was a continually evolving system of ad-hoc marks and designations. This star means X, this other slightly different bolded star means Y. This location on the board is for Z. No, not that kind of Z, that’s ZX, it’s over here! Almost every session it would change, and the meaning was impossible to keep straight.

Refining a ticket live from a sentence all the way down to an implementation formed some bizarre and terrible form of architectural jazz. Design the right way, now, from your heart. Argue the pros and cons live. Write down the first thing that comes to your head.

If you participated at all. Very quickly people started to disengage. Two engineers with strong disagreeing opinions on your team can be a great thing! There is positive progress to be found in healthy friction. Half a dozen people sitting on a call in stony silence while two people go back and forth on an idea that neither of them has had proper time to think about though? Not so great. And that’s if we could even stay on topic. Live discussion on new topics means frequently brains would catch up and have more things to say about what was said thirty minutes ago. Or, because the topics are so broad, conversations could easily split or rabbit hole. More checking out. More stony faces.

This experience solidified something I’ve been thinking about for a while.

Agile was a broad rejection of common waterfall patterns, including enormous design documents. Which is good! I don’t want to go back to not building without a 90 page spec first. I don’t want to go back to estimating how long it’ll take me to do estimates. But I think the pulling away from massive specifications has been misinterpreted to mean that no documentation is good documentation. Documentation is like lines of code; the less the better. That all work should be “agile”, in the distorted sense that it should be last minute and barely planned.

I want to push back against that. We should still be writing things down. In fact I would argue it should be the default communication you start with.

Why write things down?

1. History
2. Clarity
3. Equality

History

If you write things down, you can read them later. People who come later to the team, or inherit your work, can do so as well.

While in theory you can take notes in calls and present and log them later, almost no one does.

Clarity

If you write things down, you are forced to pay attention to what you are saying. You can spend more than a beat thinking about what you want to say. You can structure what you are saying instead of unfocused rambling. If you read things, you can read them more than once. You can spend more than a beat thinking about what the other person has said. You can dig into specific parts you need clarification on.

While in theory you can have an agenda, with a focused, clear discussion, almost no meeting does.

Equality

If you write things down, you are creating an equal playing field where everyone can contribute. If someone works best by responding immediately, they can. If someone works best by thinking about it as they do the dishes and responding later, they can.

Together with clarity and history, you create an environment that discourages “debate bro culture”, where the loudest most active voice wins through sheer aggression.

While in theory you can have calls where everyone gets a chance to speak, no one is talked over, and no one dominates the conversation, almost no meeting does.

How much?

The right amount? Not 90 pages. Obviously. But I also think it’s the wrong question to ask. It’s not the length or level of detail, it’s the action of it.

If you are tempted to get on a call to decide or discuss something, write down what you were going to talk about first. Read what you wrote. Does it make sense? Tweak it until it does. That’s your correct length.

Writing things down will lead to greater clarity of thought, more equitable discussion, and gives you a free history of decision making. All for the low low price of not getting on a call.