Your Documentation Explains Everything and Helps No One

I left rebasing out of a six-part guide to Git, and it was the best decision in the whole series.

When I sat down to write Git and GitHub for Technical Writers, I was not short of material. I had spent real time with Git, with GitHub, and with the relationship between the two, and I had a body of knowledge I was confident would be useful to other writers. What I had not yet made was the decision that actually shapes a document.

Rebasing is not an obscure corner of Git. It is one of the first things a developer will tell you to learn, and any serious treatment of the tool covers it. Leaving it out of a guide aimed at technical writers felt, at first, like an omission I would have to justify.

Then I looked at what the reader was actually there to do. A technical writer adopting Docs-as-Code needs to commit their markdown, push it, open a pull request, and not lose their work. Git and GitHub are engineering tools. For a writer they are borrowed tools, picked up for a narrow and specific purpose. Rebasing serves a concern that belongs further inside that world: rewriting commit history to keep it linear, a thing engineering teams care about and a writer, at that stage, does not. Explaining it would not have made the reader more capable. It would have introduced a second mental model of how commits move, alongside merging, before the first one had settled.

The information was accurate. It was genuinely useful. It simply did not belong in that document, for that reader, at that point. That is the decision this post is about.

Part 7 was about research: how you find out what is true, and how widely true it is. This is the stage that comes next. Research produces more than any single document should contain, and audience analysis is what decides which of it survives.

Knowledge Creates a Temptation

Coming from creative writing, I was used to the idea that having something worth saying was reason enough to put it on the page. Technical writing demands a different instinct. The question is not what do I know that I can explain. It is what does this particular reader need to know right now. That distinction sounds small, and it is not.

The trap is easy to fall into, especially early on. You learn something difficult, you finally understand it, and you want to explain it. So the terminology goes in, and the background, and the edge cases, and the exceptions, and the thing that took you three hours to work out. Before long the document has become a record of the writer's learning rather than a path through the reader's problem. Nothing in it is wrong. The writing may be perfectly good. But the reader is being asked to process information they have no reason to process yet.

The reader may not be ready for it. They may have already outgrown it. Or they may simply never need it for the task in front of them. The writer has to decide which, and the deciding is the work.

The Shift: Warehouse vs. Path

A warehouse stores everything. A path decides where someone needs to go next. Once you start designing the path, omission stops looking like incompleteness and starts looking like the point.

Selection Happens Before the Sentence

Audience analysis is usually taught as a writing technique, something you apply to prose so it lands with the right reader. In practice most of its value is spent earlier than that. It is a selection mechanism. Before you decide how to explain something, you decide whether it should be explained at all.

The questions that do this work are answered before the first paragraph exists. Who is this reader, and what are they trying to accomplish. What do they already know, and what can I reasonably assume. What is unfamiliar to them, and what have they already outgrown. What do they need to finish the task in front of them, what belongs later, and what is technically relevant but practically unnecessary. Answer those honestly and the document changes shape before a sentence is written.

There is a failure mode waiting for anyone who skips this. When you do not analyse the audience carefully, you invent one: an imaginary reader somewhere in the middle, not a beginner and not experienced, who supposedly needs a little of everything. The result is predictable. The beginner meets concepts they were not prepared for. The experienced reader wades through explanations they no longer need. The document grows longer without becoming more useful. Everyone receives information and nobody gets what they came for. That failure has a cost beyond the reading: every page written this way is another page the team maintains, updates on release, and eventually has to reconcile with a product that has moved on.

Depth Is a Decision Too

Selection is not only in or out. The same concept can enter a document at very different depths, and choosing the depth is the same decision made at finer resolution.

Branching is the example I keep returning to. A writer needs to know that a branch is a safe, separate copy of the work, how to make one, and how to get changes back into the main line. That is enough to work confidently for months. The full model underneath it, branches as movable pointers to commits, how the graph is actually assembled, is the same subject at a depth that answers questions the reader has not asked yet. Same concept. Two documents. The choice is not what is true about branching. It is how much of that truth this reader can use today.

The Uncomfortable Part

There is a humility required here that took me a while to accept. We become attached to information because we worked hard to learn it. Something cost three hours, so it feels like it has earned its place. But the effort it took the writer to acquire a piece of knowledge says nothing about its value to the reader. A concept can be genuinely difficult for me to learn and completely unnecessary for you to know.

That makes the cut hard in a way that has nothing to do with judgement and everything to do with attachment. The reader never experiences your research. They do not know how many sources you consulted or how many concepts you turned over. They experience the document, and they judge it by whether it helped them do the thing they came to do. The filtering has to happen before it reaches them, or they end up doing it themselves, which is the job you were hired to do.

So a technically impressive document can still be a badly designed one. Accurate explanations, thorough research, careful examples, and it can still fail, because it asked the wrong reader to carry the wrong information at the wrong time. The problem was never the knowledge. It was the selection.

Compressed into something you can apply, the decision comes down to three questions asked of every piece of information before it earns a place. Does it serve the task the reader came to complete. Does including it force a second mental model before the first one has settled. And is it needed today, or does it belong in the document this reader reaches next. Rebasing failed all three at once, which is why the cut was easy in the end. Most cuts are not that clean, and the questions are what make the difficult ones decidable.

Research tells you what is true. Audience analysis tells you what belongs. What neither tells you is the order it should arrive in, and a document with exactly the right information in the wrong sequence still fails the person reading it. That is information architecture, and it is where Part 9 begins.

The goal was never to transfer everything you know. It was to get this reader to the next step.