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.
If you are interested in more content covering topics like this, subscribe to my newsletter for regular updates on software programming, architecture, technical writing, and tech-related insights.
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 do you 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.
Here is an example of a template you can use.
# Example Title: Database Choice for User Data
## Context and Problem Statement
We need a scalable database to store and manage user data efficiently as our user base grows.
## Decision Drivers
* Scalability
* Data consistency
* Ease of integration with existing services
## Considered Options
* PostgreSQL
* MongoDB
* Amazon DynamoDB
## Decision Outcome
Chosen option: **PostgreSQL** because it provides strong data consistency and aligns well with our need for complex queries.
### Consequences
* **Good:** Supports ACID compliance, enhancing data reliability.
* **Bad:** May require more tuning to achieve high performance with large datasets.
### Confirmation
We’ll confirm this decision through periodic load tests and performance reviews as the user base scales.
## Pros and Cons of the Options
### PostgreSQL
* **Good:** ACID compliance, robust community support.
* **Neutral:** Setup and tuning can be time-consuming.
* **Bad:** Lacks native horizontal scaling.
### MongoDB
* **Good:** Schema flexibility, horizontal scaling.
* **Bad:** No ACID compliance across collections, limiting data integrity.
## More Information
For additional details, see the database performance evaluation [here](link-to-evaluation).
This kind of document can be present within the project repository, or a notion, or JIRA.
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. 😆
Conclusion
And that’s it for this article. We have discussed how companies and tech team leaders use ADRs to document architectural decisions on their projects and how much it helps them, teammates, or even the people who worked there after they left.
If you have experiences to share or any thoughts on the article, feel free to drop them in the comments below.
I’m always open to feedback and happy to engage in discussions that can help us all learn and grow.
If you enjoyed this article and want more insights like this, subscribe to my newsletter for weekly tips, tutorials, and stories delivered straight to your inbox!
Top comments (26)
Hey Chatgpt...
Hello Gemini..
Wow you're using Gemini???
haha ChatGPT is goated for those tasks
Claude >>>
👋 You're welcome
Now its Github Copilot....
Really needed this as documentation is something every dev is worried about! can you create a detailed guide on this tho?
Sure I will do
will it be Mangabo-generated? 😂
This helpful article for every dev, thanks.
Here in my team we adopted use RFC model, in every initiative or new software, to document, all of the fluxes.
chat GPT nè
Mistral AI
Whole-heartedly agree with this. Sadly, this is mostly ignored by the majorities. They will only realize that THEY need this when they're older and have to deal with many projects...
What a clever idea. Impressed. Thanks for sharing your secret weapon. ;)
Use sequence diagrams.
Yup. this is a tool that should be part of the ADR. I've done that before. Very useful.
How would you use sequence diagrams to document something like choice of a database? 🤔
Thank you for the article. I didn t know about ADRs.
I will definitely help me getting better.