Why nobody really likes documenting in organizations

The lack of documentation is often explained by lack of time. By pressure. By laziness. By tooling. All of that exists.

But that is not the core issue.

The real problem is that documenting, in the strict sense, is unsettling. Not because writing is hard. But because it makes visible what many prefer to keep implicit. And because it forces people to own decisions that, in real life, are not always clean.

What “documentation” are we actually talking about?

When people talk about documentation in organizations, they often mix three things together.

There is technical documentation, the kind that is put on developers’ shoulders. READMEs, diagrams, conventions, implementation choices. It is useful, but it primarily serves to keep the code running and to allow someone else to take over.

There is user documentation, produced because you have to explain “how it works”. It often comes at the end of the chain, because the truth is that there was no time before, or because people waited for the product to stabilize. It becomes a deliverable, sometimes a contractual obligation, sometimes a band-aid.

And then there is the one I am talking about here, the one most often avoided: documenting the project as a whole.

Not the technical side. Not the manual. But the mechanics of the project: decisions, trade-offs, assumptions, renunciations, the reasons that led to choosing one option over another. What was true at a given point in time. What was known. What was not known. What was deliberately ignored.

That kind of documentation is not done “at the end”. It is done during the process. And that is precisely why it is a problem.

Documenting a project means making decisions challengeable

Useful project documentation does not aim to be elegant. It aims to be explicit.

Weeks or months later, it allows people to answer basic questions without a long story: why did we do it this way, and not another? What were we trying to avoid? What did we accept to degrade? Who carried the arbitration?

Once those answers are written down, they become challengeable. Not in a legal sense. In a human sense.

You can no longer settle for “we said so”. You can no longer replay the story depending on the audience. You can no longer pretend there was no alternative. You can go back to the text and say: this is what was decided, this is the context.

And in many organizations, that is experienced as a loss of freedom.

Ambiguity is often a tool, not a mistake

Ambiguity has a bad reputation. It is presented as a lack of rigor, immaturity, or poor methodology.

In practice, ambiguity is often functional.

It allows multiple options to remain open without saying so. It avoids crystallizing a disagreement. It provides an exit if a decision turns out badly. It protects relationships, egos, and internal balances.

A deliberately ambiguous sentence in a committee meeting has enormous power: everyone hears what they want to hear. And if things go wrong, no one is clearly responsible. It is always possible to say “that’s not what was understood”.

Documenting a project reduces that comfort zone. It removes the shock absorber. So resistance is normal.

Selective memory constantly rewrites the organization

There is also a more mundane, more human phenomenon: collective memory is rebuilt over time.

Initial constraints are forgotten. Hesitations are smoothed out. Improvised fixes are replaced by a coherent story. A circumstantial compromise becomes a strategic choice. The past is reread through the lens of the present.

It is not necessarily malicious. It is often a way to keep going.

Except that project documentation, when it exists, breaks this constant rewriting. It reminds people that the decision was made under constraints. That choices were made without certainty. That minds were changed. That alignment was not complete. That rationality sometimes came after the fact.

It is useful. But it is uncomfortable.

What documentation reveals, beyond the project

Documenting a project is not only about “capturing information”. It also makes power dynamics visible.

When decisions are properly traced, you can see who really arbitrates. Who pushes for speed. Who asks for quality without providing the means. Who blocks without owning it. Who bypasses processes. Who is exposed, and who never is.

It is not a trial. It is a mirror.

And nobody really likes mirrors when they show something other than the image they want to project.

Document anyway, but accept what it implies

Once you understand that project documentation is a political and cultural issue, you stop believing that a tool or a template will solve the problem.

Documenting a project means accepting three simple, and difficult, things.

First, accepting the imperfection of decisions. A written decision will not be “beautiful”. It will be dated, contextualized, debatable.

Second, accepting that transparency creates responsibility. Writing “we made this choice because we did not have time” is healthy. But it forces you to own the constraint, and sometimes to name it.

Finally, accepting that it creates debt. A written trace must be amended when direction changes. It must be contradicted properly. It must stay alive.

This is not an ideal. It is a compromise. A choice of minimal clarity in a world that often runs on ambiguity, implicit assumptions, and rewriting.

And that is probably why, despite all the discourse, many organizations prefer to ask developers for technical documentation, or to produce user documentation at the end of the chain, rather than documenting what really matters: the project itself, while it is happening.