I would have written a shorter letter

I have made this longer than usual because I have not had time to make it shorter.

Blaise Pascal, Provincial Letters (1657)

When I write a doc for other people, most of what I know about the topic only exists in my head. The reader has none of it. They didn't look at the numbers or follow the dead ends with me. So to talk about it properly it feels like I have to put all of that on the page first, and the doc gets pretty long.

There is another reason. I don't want it to read as "trust me, bro". If I say something is a big problem, I want the proof right there next to it, so it feels like showing the work.

I don't think it is, tho. An investigation dumped into a doc shows that I did a lot of stuff. The real work is making it readable and digestible for whoever is on the other side, and a long doc is me skipping that part and handing it to them. My goal is for the doc to be read, and readers are time-poor (or sadly, an agent nowadays).

# Knowing what it's for

I can't make a doc shorter until I know what it's for. I look at a section, all of it seems relevant (because it is relevant to me), and nothing goes.

So I start with two things... why I'm writing it, and why someone would be interested in reading it.

The answer is usually because I need people to decide about something, or know something x before doing y. Once I have that, most of the doc sorts itself out. Whatever helps the reader get there stays, whatever doesn't goes, and the order mostly follows from what they need first.

Who it's for changes the bar a lot. A doc for one teammate can be messy, they can ask me. The wider it goes, the better it has to be, and the harder it is to get away with a doc that tries to do more than one thing. Half investigation and half "here's a problem you should know about" makes the reader do the sorting, and probably will make them stop reading it.

# Saying what it means

I think there is always an opinion in a concise doc that summarizes a situation. If I have a pile of numbers, I classify them, group them, rank them, and say which ones matter. I'm solving what the reader should think while they read it. Otherwise each reader has to look at every item, understand it and decide for themselves how important it is, and I already did all of that. I've been staring at it way longer than they will.

That opinion is the value I add. Anyone with access can pull the numbers, making sense of them is what took the time.

There is a counterpoint here tho, which is around biasing your readers. I get it, but that's exactly what I am trying to do at the beginning. I have intentions behind my writing. Here, for example, it's to convince you to write better.

# Writing in layers

There's a UX idea called progressive disclosure, you show people what they need for where they are, and reveal more as they go. I think writing should work something like that (this was a great advice I got from my manager once, he thought that, and I agree, so now I also think that)

The very top is generic and clear. It says what this is about and what I want from the reader, so they can tell in a few lines if it's for them. Most people stop there, they got what they needed. Whoever keeps reading gets more detail, and the further down they go, the more into the weeds it gets. Nothing the reader needs to decide should live only at the bottom, since most of them won't get there.

# The worry about misreading

The strongest pushback I have against all this is that if I remove the context, they'll misread it, or decide on half the picture. The detail was there for a reason.

I don't think they can misread it if the opinion is stated. When the doc says "this is what's happening and this is the part that matters", there isn't much room to read it some other way. They can disagree, sure. If they do, that's when they dig further and we talk about it. I'd much rather have that conversation than have someone quietly draw a different conclusion from a table I never explained.

The evidence doesn't go away either. It moves to the bottom, a side doc or whatever makes sense with the medium used to share this writing in the first place. Most people won't open it, it's there for the few who want to check. It also handles the "trust me, bro" worry better than the body did, since most readers would have skipped that part anyway.

# It feels like losing things

Cutting is uncomfortable when I know everything about the topic. Every paragraph I remove was something I found out, and the doc starts to feel like it's missing stuff, like I didn't do enough. But the reader never knew what was cut, so they don't miss it.

It also feels way shorter, even if it isn't. Once the opinion is at the top and the details sit below it, the doc can be almost as long as before and still read fast, because from the first lines the reader knows what they're looking at. The docs I like best have nothing in them meant to impress anyone, they say clearly what has to be said and that's it.

# When I'm not ready to send it

All of this assumes I already have the opinion. Sometimes I don't. I have numbers and I don't know what they mean yet.

Then I probably need to do a bit more work before sending anything out. It's fine to jump-start it with a few peers, show them the messy version and work out what it means together. But if it's going to a wider pool of people, it should be ready, and I should know those answers. If not, I'm just pushing a lot of work upwards rather than solving it myself.