Your Documentation Only Knows What One Person Noticed

Thirty of us went on the same picnic. Only a few came back with the real story.

I must have been twelve. We spent a day out as a class, and afterwards the teacher set us an assignment: write a story about the picnic. We had all been there. We had all seen the same day.

Most of the class wrote from memory. The food, the field, the long bus ride home. Some of it was lovely. But every story was the same size, bounded by what one child could notice in a single afternoon. A few students did something different. They went around asking. They asked classmates what had happened at the far end of the field. They asked the guides why the schedule changed. They even asked strangers who happened to be there.

Those students came back with things no single pair of eyes could have caught: the reason behind the delay, the moment that happened while everyone else was looking the other way. Same day. Same hours. Completely different documents. The difference was not talent, and it was not better sentences. It was research.

Most people think research means finding out more about a thing you already broadly understand. That is part of it, the smaller part. Research is the act of treating your own view as incomplete on purpose, then going to find the rest of it. The students who wrote from memory were not lazy. They simply trusted that their one view of the day was the whole day. It never is.

In Part 6, I argued that assumption is the enemy of accurate documentation. This post is about the antidote. Research is the first of the three stages that come before you write a single sentence, and it is the one everything accurate is built on. Not because it is a box to tick, but because a document is only ever as complete as the sources standing behind it.

What Research Actually Is

When most writers research, they go looking for confirmation. They already sense what the document will say, and they collect the facts that agree. This feels productive. It is mostly decoration. You are not learning anything: you are assembling evidence for a conclusion you reached before you started.

Real research runs the other way. It begins by treating the gaps in your understanding as the most important part of the work, and it draws on more than one kind of source to close them. The product you use and the people you interview are primary sources, the ones you generate yourself. The existing docs, the support tickets, the release notes are secondary, someone else’s account of what happened. A strong document is built from both, and it never mistakes one for the other.

That willingness is the discipline. Everything after it is technique.

The Shift: Observation vs. Inquiry

Who You Ask Is the Whole Job

The students who wrote the best stories did not stop at one classmate. They moved between many: friends, guides, strangers. Each held a fragment. The story lived in the assembly of those fragments, not in any one of them.

There is a discipline behind that instinct, and technical communication has a name for it: stakeholder consultation. Before you write, you map who holds a piece of the truth, then you go to each of them in turn. On a documentation project that map is more obvious than people assume.

The product itself is the first source, and the only one you can interrogate without asking anyone. You walk the process, you click the buttons, you break it on purpose to see how it behaves when someone does the wrong thing. After that, every source is a person, and each one knows something the others structurally cannot. Engineers know why a thing was built the way it was, which is often more useful than knowing what it does. Support knows the questions users actually arrive with, not the ones you imagine they have, and that gap is wider than most writers admit. The users themselves, the source most writers never think to consult, know the one thing none of the others can see: where the product stops making sense to a person meeting it for the first time.

The right questions matter as much as the right people. A weak question asks what does this do. A strong question asks what happens when someone does this wrong, where do people get stuck, what did you assume everyone already knew. Those last questions surface the details that decide whether a document works, and they are usually the ones nobody thought to mention, because they seemed too obvious to say out loud.

On real documentation projects, the same feature rarely has a single description. Ask an engineer to describe it and you get the language of how it was built. Ask support to describe the same feature and you get the language of how it breaks. The two accounts rarely match, and the gap between them is almost always where the documentation needs the most work, because it is the part of the product that is hardest to explain. You only find that gap by asking both.

No single source is the last word, which is the real reason you consult several. Where independent sources agree, you can trust the fact. Where they contradict one another, you have found the exact point the document needs to resolve. Researchers call this triangulation. A claim earns its place not when one person asserts it, but when it holds from more than one direction.

Test What You Are Told

Asking is only half of it. The other half is refusing to take any answer on trust until you have watched it hold.

A subject matter expert hands you the steps to install the product. You write them down, cleanly, in order. Then you do the thing that separates a document a reader can trust from one that merely sounds right: you run the steps yourself, exactly as written, on a machine as bare as your reader’s. Step four fails. It assumed administrator permissions the engineer never mentioned, because the engineer has always had them. Your reader does not. You only know that gap exists because you walked it. The expert was not wrong. They were complete for themselves and incomplete for the person you are writing for, and only verification finds the difference.

Research has an opposite failure too, and it is quieter. You can consult so widely and gather so much that the document drowns before it is written. So the discipline is not only knowing who to ask. It is knowing when the picture is whole enough to draw, and stopping there. The signal is convergence, not exhaustion: when the next person you ask only confirms what the last three already told you, the research is done. You stop because the answers have started to agree, not because you have run out of people to ask.

Compressed to something you can carry, this stage is two questions asked of every claim before it reaches the page: did I watch it hold, and did it hold from more than one source. The first is verification. The second is triangulation. A fact that cannot answer both is not documentation yet. It is a guess in a confident voice.

Research tells you what is true, and how widely true it is. But not everything true belongs in the document. The next stage decides which of everything you have gathered this particular reader actually needs, and in what depth. That is audience analysis, and it is where Part 8 begins.

Ask widely. Trust nothing untested. A document is only as honest as the search behind it.