Most teams I have worked with agree that documentation matters. That agreement does not create time to write it.

A production issue has a customer waiting. A regulatory change has a deadline. A feature is expected in the next release. Documentation usually has no equivalent pressure, so postponing it is often the most reasonable decision in the moment.

Teams understand the value. They still postpone it because today’s work has a deadline and documentation usually does not.

Asking a person is often the fastest option

When the knowledge owner is available, asking them is usually faster than finding and reading the relevant documentation. A short conversation can resolve the question and let the team continue.

Under delivery pressure, this is efficient. It also creates a habit: the person becomes the most reliable interface to the knowledge.

For a while, that arrangement works well. The weakness only becomes visible when the person is on leave, changes team or leaves the organisation. The answer may still exist somewhere, but the quickest path to it has disappeared.

The work has not been avoided

A decision that is not documented does not necessarily create an immediate problem. The feature can still ship and the customer can still receive the fix.

The cost appears later, when somebody has to reconstruct the same reasoning from code, tickets, meetings and partial memories. What was once a fifteen-minute note can turn into several hours of investigation.

In practice, documentation is not extra work added after delivery. It is a choice about when the understanding will be paid for, and by whom.

Writing everything is not the answer

The useful part of documentation is rarely a complete description of the system. Large documents become difficult to maintain and are often the last place people look.

What tends to survive better is the information that cannot be recovered easily from the code:

  • why this option was chosen;
  • which alternatives were rejected;
  • which business assumption the behaviour depends on;
  • who owns the decision;
  • what would require the decision to be revisited.

These details are small enough to capture while the context is fresh and valuable enough to save someone from rebuilding it later.

Timing matters more than intention

Teams often plan to document after implementation. That is exactly when attention has already moved to the next subject.

A more realistic approach is to attach documentation to moments when understanding changes: after a decision, after a workshop, after an unexpected production finding or before a handover. The format can remain light. What matters is recording the part that will otherwise live only in someone’s head.

Documentation will probably never beat urgent work on its own. It needs a deliberate place in the workflow.

That is why I think of it as work for tomorrow. It is written today so that the next person does not have to repeat today’s analysis from the beginning.