How to document technical decisions so they don’t get lost

6 months ago we decided not to use a particular caching plugin on a project. We discussed it in a meeting, reached a consensus and moved on.

Last week, a developer who had just joined asked why we weren’t using it and suggested installing it. I spent 20 minutes explaining something we had already decided.

It’s not the end of the world, but I’m not getting those 20 minutes back. Multiply that by every technical decision on a project lasting several months and by every new person who joins. The result is whole days of repeated conversations.

Documenting technical decisions isn’t unnecessary bureaucracy. It’s insurance against forgetting. And forgetting is expensive.

Why decisions get lost (and why it hurts)

In development teams, technical decisions have a short half-life. The reasons are predictable:

Team turnover. The person who made the decision has left. Whoever replaces them lacks the context and assumes the current decision has no reason behind it.

Time. 8 months ago you decided not to use React because the project didn’t justify it. Now it has grown and someone suggests migrating. And you wonder: was it a conscious decision, or did nobody on the team know React well back then?

Changing context. Decisions are made with the information available at the time. That information changes, and the decision should be reviewed. But if you don’t know what drove it, you can’t tell whether the change matters.

Informal communication. “We talked about it on Slack”, “it was agreed in the meeting”, “John knows”. Slack disappears into the endless scroll, meetings aren’t recorded and John has moved to another company.

What makes a good decision record

At Baqueiro we use a simple format we call a Decision Record (DR). We didn’t invent it: it’s based on Architecture Decision Records (ADRs), a fairly widespread practice in the industry, simplified for small teams.

Each DR has 5 sections:

1. Context. What problem were we solving? What constraints did we have (budget, deadlines, team knowledge)? What alternatives did we consider?

2. Decision. What did we choose? It has to be specific: “we’ll use Laravel with Laravel Nova for the admin panel”, not “a modern solution”.

3. Consequences. What do we gain and what do we lose? Every decision involves trade-offs, and a good DR is honest about them.

4. Date and participants. When was it made and who was involved? That way you know who to ask if questions come up.

5. Status. Is it current, superseded or reviewed? Decisions change, and the DR has to reflect that.

Where we keep Decision Records

Format matters, but location matters more. A DR in a document nobody opens is useless.

We keep them in 3 places, depending on what they cover:

Project-specific decisions: in the repository itself, in a /docs/decisions/ folder. Next to the code and versioned with it. It’s the first thing you see when you open the project.

Cross-cutting architecture decisions: in the team wiki, organized by area (frontend, backend, infrastructure), because they affect every project.

Decisions about tools and processes: in Notion, alongside our internal procedures. For example, why we use Figma rather than Sketch.

The rule is simple: documentation has to live where someone would naturally look for it at the moment the question comes up.

When to create a Decision Record

We don’t document everything, because that would be paralyzing. We create a DR when:

• The decision is hard to reverse (framework, database, service architecture).
• We expect someone to question it later (people joining the project, growth).
• There are reasonable alternatives others might suggest, and we want to make clear why we ruled them out.
• The decision affects other people’s work (processes, shared tools).

We don’t create DRs for trivial decisions (using snake_case for table names), obvious ones (using HTTPS) or anything the code already explains by itself.

An example Decision Record

This DR is based on one of our projects, anonymized and slightly simplified:

DR-014: We will not use Elasticsearch for product search

Date: September 2024

Participants: technical lead, backend lead, systems lead

Context: The client has around 3,000 products and wants advanced search (combined filters, sorting by relevance). The backend side proposed implementing Elasticsearch to improve search performance and capabilities.

Decision: We will use MySQL’s native search with optimized indexes. We will not implement Elasticsearch at this stage.

Reasons:

• A catalog of 3,000 products is comfortably within what MySQL with good indexes handles well.
• Elasticsearch would complicate deployment: it needs an additional server or a managed service.
• The team has no experience running Elasticsearch in production, and the risk of infrastructure problems currently outweighs the benefits.
• The client has no budget for the additional infrastructure.

Consequences:

• We search using MySQL FULLTEXT indexes and optimized queries. Performance is acceptable for the current volume.
• We won’t have typo-tolerant search or advanced relevance scoring.
• If the catalog grows beyond 10,000 products or the client needs more sophisticated search, we will have to reconsider.

Status: Current. Review if the catalog exceeds 10,000 products or if the client asks for search features MySQL can’t provide.

A few months later, someone asked: “why aren’t we using Elasticsearch?”. We sent them the link to DR-014. The conversation took 3 minutes, not 30. The decision stood because the context hadn’t changed.

How to keep Decision Records up to date

An outdated DR is worse than none at all, because it gives false confidence in a decision that no longer applies.

Our rule: whenever someone questions a documented decision, its DR gets reviewed.

• If it stands, we add a line: “reviewed on [date], context unchanged”.
• If it changes, we mark it as superseded and create a new one that explains the current context and links to the previous one.

Over time this builds a history that is valuable in its own right: you can see how the architecture evolved and why. For onboarding someone new to the project, it’s gold. It’s the same logic we apply to automations, where a lack of documentation turns every change into archaeology, as we explain in the hidden cost of poorly documented automations.

Common objections

“We don’t have time for this.”

Writing a DR takes 10 to 20 minutes. Debating the same decision 3 times because it was never written down takes hours. It’s simple math.

“The code is documentation enough.”

Code explains what was done, not why. And the why is exactly what gets forgotten and is hardest to reconstruct.

“Nobody reads documentation.”

If nobody reads it, the problem is where it lives or how it’s organized, not documentation itself. A DR in the repository turns up naturally when someone works on that part of the code.

“Decisions change constantly, we’d end up with a mess of outdated documents.”

If something changes constantly, it shouldn’t be a DR. DRs are for decisions with lasting consequences. If it changes every week, it’s configuration, not architecture.

Frequently asked questions

Should the client see the Decision Records?

It depends. The ones that affect business decisions, yes. Purely internal ones, no. For clients with a technical profile we keep a summarized version.

What if someone ignores a DR and does whatever they like?

DRs aren’t laws, they’re the record of a consensus. If someone wants to change a decision, it gets discussed and the DR is updated. Ignoring it is a team culture problem, not a documentation problem.

Do we need a special tool?

No. A Markdown file in the repository works perfectly well. What matters is the habit, not the tool. If you want to start today, create the folder, write a DR for the last decision your team has debated twice and number it DR-001.

Conclusion

Documenting technical decisions isn’t an excuse for not making them, or bureaucracy to justify the status quo. It’s respect for future time: yours, when you can’t remember why you did something; your team’s, when someone joins a project already under way; and that of whoever inherits the code a few years from now.

If your team wastes time debating decisions that have already been made, or you join projects without understanding why they were built that way, you may be missing a Decision Records process. At Baqueiro we can help you put one in place without complicating the way you work. Tell us how your team works today.