I once spent 3 months writing a technical document that no one ever read.

There was a bunch of legacy systems that needed to be replaced, but their interaction and dependencies were not clear. The project manager in charge of the replacement hired me as an external consultant to draw the map.

Nobody knew or cared about these old systems. The people who originally designed them had long left the company. I went around asking questions and bugging people. The result was an architectural overview that had loads of assumptions but painted an overall picture. I mailed the first draft to all stakeholders and eagerly awaited their feedback.

I’m still waiting.

Clients love documentation. It’s a quality seal. A well-documented system is trustworthy.

But documentation often becomes a mindless must-have. That’s a real risk. If documentation means quality, then surely more documentation means higher quality, right?

In the case of my legacy architecture draft, the problem was clear: documents for the sake of documents. I was writing the wrong thing for the wrong people.

Niche down

When writing, the first question should be “for whom?”. The audience shapes the document. Is it a technical guide for the next developer? An architectural overview for the CTO? A user manual?

You can’t write a book for everyone. That’s not how it works. You target an audience and niche down. Leaving the spaceships out to appease a certain crowd, will push away the sci-fi fans.

Pick an audience and aim only at them.

Split up

Often there will be multiple audiences. It’s better to write a different document for each of them. People demand focus. They don’t want to wade through a bunch of irrelevant prose.

The size of the audience is not important. The value the document brings them is all that matters. If one helpdesk engineer can support multiple customers using your FAQ, that’s a win.

Scale down

People don’t read huge PDFs. Less is more and double so for documents. It’s not that we feel obliged to write lengthy documents. It’s that we worry that a one-pager will feel as “not enough”. A short document is better. It’s also much harder to write.

If you have a lot of information to compile for a single audience, it might be valuable to split up again. Multiple documents for the same audience can work wonders.

Reach out

Talk to your audience before putting down a single letter. Reader interviews are crucial in identifying your audience and in gathering their needs.

In most cases, the documents I had in mind at the start would not have been relevant to the reader. Readers need to tell you what they want to see. An engaged audience creates a great document. A silent audience often means the whole thing isn’t worth writing.

So what went wrong with my legacy architecture overview? It was a helicopter view of systems that nobody asked for. It was a book no one cared to read.

If I would have listed the components that needed to be replaced and their specs, the developers would have been thrilled.

If there was a document that listed the departments that were responsible for each of the components, the functional design team would have devoured it.

Instead, I wrote a book that tried to be everything to everyone. And as is the case with most of those dry, heavy tomes, most people only claim to have read them.

Books written for everyone, are read by no one.