Software Documentation That Preserves the Why Behind Decisions

I recently gave a presentation at Zylo on a topic that usually only gets attention when something goes wrong: documentation.

Not documentation for the sake of writing more files. Documentation for preserving context, decisions, assumptions and reasoning.

Why expensive problems are rarely about code

In real projects, the costly problems are often not caused by bad code. They come from questions nobody can answer anymore:

• Why was this architecture chosen?
• What exactly did the client mean by this requirement?
• Which edge cases were already discussed?
• Why does this API behave this way?
• What changed during development, and why?

The code tells you what happened. Good documentation tells you why.

Document across the whole lifecycle

Documentation is not a final phase. It belongs in every stage of delivery:

Discovery → Requirements → Design → Build → Release → Operate

What to capture at each stage:

1. Discovery: the problem, who has it, and what success looks like.
2. Requirements: what was agreed, what was explicitly left out, and open questions.
3. Design: architecture choices and the alternatives you rejected, with reasons.
4. Build: API behaviour, data models, and non-obvious implementation decisions.
5. Release: what shipped, what changed since the plan, and known limitations.
6. Operate: runbooks, monitoring, common failure modes and how to fix them.

Timing matters most

The most important rule I shared is about timing. Write documentation when the decision is made, not weeks later when someone remembers to document the project.

Weeks later, you remember the outcome but not the reasoning. The reasoning is exactly what the next developer needs.

A good, lightweight format for a decision is four lines:

Decision: Use a shared schema with a tenant column.
Context: ~hundreds of similar tenants, small ops team.
Alternatives: Separate database per tenant (higher cost and complexity).
Consequences: Every query must be tenant-scoped; add isolation tests.

Never silently turn a gap into an assumption

This is the habit I feel most strongly about. When a requirement is unclear, it is tempting to pick the most likely interpretation and keep building.

Do not. If something is unclear:

1. Ask.
2. Get a confirmation.
3. Document the answer.

A silent assumption becomes a hidden requirement, and it usually surfaces at the worst possible moment, such as a client demo or a production incident.

Where AI helps, and where it should not

AI can make documentation much easier. It can draft pages, review them for gaps, find contradictions between documents, and flag information that has gone stale.

But AI should accelerate documentation. It should never become the authority for it. A model does not know why your team made a call unless a person told it. The reasoning has to come from the people who were in the room, which is also why I argue that AI is not a substitute for thinking.

A short starting checklist

If your team has little documentation today, start here:

• Keep a decision log, even a single shared file.
• Write a short README that explains how to run, test and deploy.
• Record every confirmed requirement clarification.
• Add a "why" comment above any code that looks strange but is intentional.
• Review docs when the code changes, as part of the pull request.

The takeaway

Good engineering is not only writing code that works. It is also preserving the reasoning that helps the next developer understand why that code exists. That next developer might be you, in six months.