As a software engineer, I've worked in a wide range of tasks. These include tasks with a defined scope, containing numerous decisions and well-documented rules, as well as tasks that require more exploration to be completed but still have a certain date to be deployed. For the latter, the scope can be adjusted if we encounter conflicts, overlaps, or other issues along the way.
When a conflict is found during the task execution I would probably ask the reporter what to do and give some suggestions over a call or Slack and continue with the implementation. What happens a month later when someone asks why this addition to the scope is in production, though?
I can decide to simply look directly at the code, which would take a while to understand and refresh my mind on that topic, but with good commit messages and PRs in addition to a clean code base I would find an answer at some point.
That being said, I wanted to suggest a simpler approach that can be implemented during or right after the call. This method ensures that the information remains publicly available, even for non-technical people. Decisions can be added to the ticket as a comment, or to a documentation page if the concept is too complex to fit in a comment.
What is ADR?
An Architecture Decision Record (ADR) is a document that records a significant architectural choice made, including the reasons and results. There are some examples in this repository that you can take as reference.
Start simple
For now, you can start with a simple approach. If your team doesn't have a culture of creating documentation yet, begin by adding context to the Pull request description, as code comments or as a markdown file. Explain the issue, the decision and the consequencies and gradually provide more details in the ticket. Eventually, create a small repository of documentation and share it with your team, that’s really important especialy on larger groups of people.
Keep improve as you go
That all being said, you can keep this mindset and use the tools you already have to document your decisions. In the example I gave in this post, I mentioned “ticket” but you can use any other tools such as Linear, Notion, Confluence or any other tool. The goal is to keep the decision and its whys available and transparent to everyone on the team.
