There’s one task that software engineers hate, yet this small attention to detail is what separates a good software engineer from a bad one: How do they document their project?📝

A few years ago, I was responsible for setting up a fintech project. Because we decided to move quickly, planning for scalability wasn’t a priority. Our focus was on validating the idea, so we pushed forward, creating APIs, architectures, and systems with simple solutions, not overly concerned about the future.

However, as the person in charge of the backend and infrastructure, I knew that while my memory was reliable, it wouldn’t be enough to recall all the details six months down the line.

In my research, I discovered a convention I liked: ADR, or Architectural Decision Record.

It’s essentially a document that traces all changes made to an architecture: the change itself, its impact, and what we learned from it.

Think of it as a personal journal but for the team.

Why is it important?

• Humans forget: Documenting changes helps us because we easily forget the reasons behind choosing one architecture over another.

• It makes the team better: Let’s say you’ve tried various solutions for an issue and documented the successes and failures. You learn from it, and others can too, even developers who come in after you.

• Future developers will thank you: Imagine a dev coming to a codebase and trying to understand why a change was made five years ago. Somewhere, a developer is likely struggling with this because the previous engineer left without documenting it, and they’re not thrilled. Meanwhile, in another company, a developer finds an ADR explaining those changes, and they’re incredibly grateful.

How to write one then?

There are several conventions to follow, but you can always adapt them to what works best for you.

The convention that inspired me is here: https://adr.github.io/madr/. You can also check Amazon’s ADR process here: https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/adr-process.html.

In my last company, where I worked as a frontend engineer, we didn’t have a single document for all architectural changes.

Using GitLab issues and linking every change to an issue branch helped us track the reasons behind changes, even months after implementation.

This practice saved us countless times. As I always say, no matter how smart you or your teammates are—your CTO, manager, or anyone involved in the project—they won’t remember every technical decision made two years ago.

Unless, of course, you’re working with 10x engineers. 😆

That’s what I wanted to share this week. I haven’t been putting out as much technical content because topics on career growth and software engineering productivity seem to get the most engagement.🤨

However, I’m documenting some thoughts on CQRS and Event Sourcing on LinkedIn, but I’m also planning on publishing next week a solid article on how banks use this pattern and how to implement it in your application.