Introduction

“Working software over comprehensive documentation” states the Agile Manifesto. Yet this mindset is, in my eyes, seriously overused in our industry. I’ve been in countless situations where I found myself asking why certain decisions were made. Why is this logic implemented in such a strange way? Why was this pattern chosen? Why did we pick this technology? You may notice I use the word “why” a lot. That’s intentional. I can see how something works and when it changed by looking at Git history. What’s usually missing is why it was done in the first place.

Explaining the rationale behind decisions is extremely important - not only in engineering but in most areas of life. If you’re curious, Simon Sinek talks about the importance of “why” in his book “Start with Why”. Understanding the “why” gives you context, constraints, personal opinions, and long-term vision. Once you know why, everything else starts making more sense.

As engineers, we make decisions all the time. We shape how systems will look, choose architectures and patterns, pick tools, and set priorities. Some decisions are tiny and harmless. But others are huge - they ripple across teams, products, and even entire departments. And these big decisions need more attention.

The Power of the Written Word

The written word is powerful in many ways:

• People may leave, but written words stay.
• Writing things down helps reduce overthinking, anxiety, and stress - like cleaning your desk to clear your mind.
• Writing helps you form and structure your ideas better.
• Written documents can be referenced long after memories fade.
• Collaborative writing improves teamwork and alignment.

These principles map neatly to engineering too:

• Documented complex logic can be handed over easily during vacations, sick leave, or departures - like leaving instructions for someone watering your plants.
• Large feature planning becomes clearer when supported by written requirements or design docs.
• You can revisit documentation to understand why a decision was made.
• You can gather feedback and insights from peers.

This all sounds useful, but should we document every decision? Absolutely not. Otherwise, we’d be back to waterfall-era paralysis, where nothing moves because everyone is writing 50‑page documents nobody reads.

When To Document

Ralph Johnson described software architecture as “the design decisions that need to be made early in a project.” He later refined this to: “Architecture is about the important stuff. Whatever that is.” So, we should document the important decisions. Sounds simple… until you have to decide what’s actually “important.”

Important decisions are:

• Hard to change
• High impact
• Heavy in consequences

How does this translate to real life?

• Choosing React as a web framework is hard to undo once your app grows large.
• Opting for microservices affects team structures, workflows, and deployment pipelines.
• Introducing new observability tooling influences platform cost.
• Picking library A over library B brings both its benefits and its drawbacks.

Important decisions have a wide blast radius. They affect not just you, but your team, other teams, your company, and ultimately your customers. Documenting these decisions gives everyone the confidence that we’re aligned and moving in the same direction - like leaving a clear map before the road trip starts.

How to Document

Once you agree a decision is worth documenting, the next question is: how? Different companies and situations call for different formats. Here are the ones I’ve seen most often.

Intent to Act

The simplest form: a message in a general chat stating what you plan to do.

Example: “Hey, I want to upgrade our test environment with the latest security patches, so it will be unavailable for about half an hour after lunch. Let me know if you have any objections.”

And notice - we still explain the “why”: security patches.

Decision Log

A page with a table listing smaller decisions made by the team. Columns might include decision name, description, owner, date.

Example: “Deny public access to S3 buckets and use signed URLs to comply with our security strategy.”

Short, clear, and it states the intent.

Architecture Decision Record (ADR)

A dedicated page documenting a single decision. Many templates exist. My preferred structure: context/problem → options → decision → implications.

Example: “Use Next.js as our web framework because we need server-side rendering and strong SEO support. We prefer Next.js for its Vercel hosting capabilities, our team’s existing expertise, and its fit with our long-term front-end strategy. This choice will require major application refactoring, which business stakeholders have agreed to prioritize and fund”.

We make the business reasoning explicit.

Design Document

Also known as an RFC or Request for Comments. This one covers a larger scope - maybe a new feature, project, or large system change. It can reference smaller ADRs to keep everything clean and focused.

Example: “Replacing client-side rendering with server-side rendering.”

This can include an ADR for selecting Next.js, plus sections like migration strategy, risks, rollout plan, and timelines.

What to Document

“Everything should be made as simple as possible, but not simpler” - Albert Einstein

Documents should be compact and to the point. They should contain only information that cannot be expressed clearly in code. For example, API definitions should live in an OpenAPI file, not in a document that will be outdated in two sprint cycles.

I follow a few simple rules:

• Audience: Who will read this? Adjust detail and complexity accordingly.
• Bus Factor: If I disappear, will people understand the reasoning and move forward?
• Evaluated Options: Did I capture all options that were considered?
• Advantages/Disadvantages: Have I listed the trade-offs honestly?
• Risks: Did I outline the risks?
• Consequences: Did I consider the potential impact?
• Scope: Who will this decision affect, and how much buy‑in is needed?

These elements ensure the documentation is helpful, clear, and gives readers insight into the thinking that led to the decision.

Conclusion

Documentation should not be seen as a chore. It’s a tool for sharing thoughts, working with others, getting feedback, and aligning on common goals. If we learn what, when, and how to document, we gain skills that make us better leaders and better engineers.

So grab your markers, your keyboard, or your favorite digital notepad - and enjoy your next writing session! ✍️