Most organisations approach documentation the same way. They identify a need, find someone to do the writing, and ship whatever comes out. Then they wonder why the documentation does not work.

The problem is not the writing. It is everything that happened before the writing.

Documentation that fails almost always fails for the same reasons: the structure was not thought through before the first word was written, the audience was not clearly defined, the scope was not agreed, and the information was not validated with the people who actually know how things work. The writer sat down in front of a blank page and did their best. Their best was not enough, not because they could not write, but because the thinking that should have preceded the writing had not been done.

This distinction matters more than most organisations realise. Because as long as you believe documentation is a writing problem, you will keep solving it by finding better writers. And you will keep getting the same results.

The thinking problem in practice

Consider how most technical documentation gets created. An engineer ships a feature. Someone notices it is undocumented. A technical writer is briefed, often by the engineer who built it, often quickly, often without a clear sense of who the documentation is for or what it needs to achieve. The writer produces something. It ships alongside the feature. It is never quite right, and nobody has the time to fix it.

This pattern is so familiar it has become invisible. Documentation that is slightly wrong, slightly incomplete, slightly out of date is treated as a normal condition of the product, not as a fixable problem with real consequences. Support tickets pile up from users who could not find the answer they needed. New hires take weeks longer to onboard than they should. Enterprise buyers ask for documentation that does not exist.

The root cause is always the same. The questions that should have been answered before the writing started were never asked.

Who is reading this? What do they already know, and what do they need to learn? What do they need to be able to do after reading it? How does this document relate to the others around it? What is the right level of detail, technical enough to be useful, accessible enough to be understood? Where will this document live, and how will people find it when they need it?

Without answers to these questions, even the best writer in the world cannot produce documentation that works. They can produce documentation that reads well. That is not the same thing.

Why organisations keep getting this wrong

The persistence of the writing-problem framing is not accidental. It reflects a broader tendency to treat documentation as a form of content: something that is produced, shipped, and moved on from, rather than as a system that is designed, built, and maintained.

Content has writers. Systems have architects. And the discipline that documentation actually requires is architecture, not writing.

There is also a resourcing dynamic that reinforces the problem. Documentation is typically treated as something that happens at the end of a project, after the real work is done. The people involved in the actual work, the engineers who built the system, the product managers who defined it, the compliance officers who approved it, have moved on to the next thing. What remains is a brief, a deadline, and a writer who was not in the room when the decisions were made.

The writer does what they can with what they have. They produce something. It gets shipped. And the cycle continues.

Breaking this cycle does not require better writers. It requires a different understanding of what documentation actually is, and a different process for how it gets created.

Structure before prose. Always.

The discipline that separates documentation that works from documentation that does not is information architecture: the deliberate design of how information is structured, organised, and navigated before a single word of content is written.

Information architecture asks the questions that most documentation processes skip entirely. What are the components of this documentation system? How do they relate to each other? What is the logical hierarchy? What belongs in this document and what belongs elsewhere? How will a user navigate from where they are to what they need? What happens when the product changes, and how does the structure accommodate that?

These are not writing questions. They are design questions. And they require a different kind of expertise than writing requires.

When structure is designed before prose is written, several things happen that do not happen any other way.

The writing becomes easier. A writer who is given a well-designed structure does not need to make decisions about what to include, how to organise it, or where to draw the boundaries between sections. Those decisions have already been made. The writer can focus entirely on the quality of the prose, because the architecture has already done the heavy lifting.

The documentation becomes more consistent. Structure imposes consistency. When all documentation within a system follows the same architectural logic, the same hierarchy, the same naming conventions, the same organisational principles, and users learn the system once and can navigate it reliably. They do not have to re-orient themselves every time they open a new document.

The documentation becomes more useful. Documentation designed around what the reader needs to do is fundamentally different from documentation organised around what the writer found it natural to say. The former answers the question the user actually has. The latter answers the question the writer found easiest to address. These are rarely the same question.

The documentation becomes more maintainable. When a product changes, documentation built on a well-designed architecture can be updated predictably and efficiently. The structure tells you exactly which documents need to change and why. Documentation with no underlying architecture requires a full review every time something changes, because nothing is predictable about where information lives.

The five questions that should precede every documentation project

In practice, the shift from a writing-first to a thinking-first approach to documentation starts with five questions. These questions should be answered before any writing begins, and in many cases, before any writing is commissioned.

1. Who is this documentation for?

Not in the abstract. Specifically. Is this for a first-time user who has never encountered the product, or for an experienced user trying to accomplish a specific task? Is it for an engineer integrating with an API, or a compliance officer preparing for an audit? The same product may require multiple distinct documentation audiences, each with different needs, different levels of technical knowledge, and different goals. Documentation that tries to serve all of them in the same document serves none of them well.

2. What does this audience need to be able to do?

Documentation is not an end in itself. It is a means to an end: that a user can accomplish something they could not accomplish before reading it. Every piece of documentation should have a clear answer to this question. What specific outcome does a user achieve after reading this? If the answer is vague, the documentation will be vague. If the answer is clear, the documentation can be written directly toward it.

3. What information is genuinely necessary?

More is not better in documentation. The instinct to be comprehensive, to include everything that might possibly be relevant, produces documentation that is exhausting to read and impossible to navigate. The discipline is to include what is necessary and nothing more. This requires thinking about what a user already knows and what they need to learn, and being ruthless about the difference. Every sentence that does not need to be there is a sentence that makes the documentation harder to use.

4. How does this documentation fit into the broader documentation system?

No document exists in isolation. It relates to other documents: documents that provide context, documents that go into more detail, documents that cover adjacent topics. The architecture of the documentation system defines these relationships. Without that architecture, each document becomes an island, disconnected from the information that would make it more useful and harder to find from the adjacent documents that would naturally lead to it.

5. How will this documentation be maintained?

Documentation is not done when it is published. A product changes, and the documentation must change with it. A process is updated, and the documentation must be updated. A regulation changes, and the compliance documentation must reflect the change. The question of how documentation will be maintained is not a question for after the documentation is published. It is a question that should shape how the documentation is structured and written in the first place. Documentation that is easy to maintain is documentation that has been designed with maintenance in mind from the beginning.

The organisational implication

If documentation is a thinking problem, the solution is not to hire better writers. It is to create the conditions in which the thinking can happen before the writing starts.

That means allocating time and resource to documentation architecture before documentation production. It means involving the right people in the design of documentation structures, not just the review of documentation drafts. It means treating documentation as a discipline that requires expertise, the kind of expertise that most organisations do not currently have in-house and do not currently recognise they need.

It also means changing the point at which documentation enters the product development cycle. Documentation that is written after the fact will always reflect what was built rather than what users need to understand. Documentation that is designed alongside the product, with the same rigour applied to its architecture as to the product's own design, will reflect what users actually need from the beginning.

This is a significant shift. It requires a different kind of investment, a different kind of process, and a different understanding of what documentation is for. But the organisations that have made this shift share a common characteristic: their documentation works. Not occasionally. Consistently.

The organisations with the best documentation are not the ones with the best writers. They are the ones with the clearest structures, the most disciplined processes, and the deepest understanding of what their documentation needs to achieve.

The writing, in the end, is the easy part. Always has been.

What this looks like in practice

The shift to thinking-first documentation does not require rebuilding everything at once. It starts with one question asked at the beginning of every documentation project: have we done the thinking before we start the writing?

Have we defined the audience? Have we agreed what this documentation needs to enable? Have we designed the structure? Have we involved the right people, not just to review what is written, but to shape what is built?

If the answer to any of these questions is no, the writing has not yet been earned. The thinking still needs to happen. And the organisations that internalise this discipline, those that make it a standard part of how documentation gets created, not an occasional exception, are the organisations whose documentation consistently works.

The thinking is not glamorous. It does not produce a deliverable that looks finished. It produces a structure, a plan, a set of decisions: the invisible foundation that makes the visible documentation possible.

But without it, all you have is words.