Michael Nygard, the inventor of Architecture Decision Records, has a great blog post to start with.
Even in ThoughtWorks Technology Radar, ADRs are mentioned as Lightweight Architecture Decision Records.
In his blog post, Michael Nygard discusses storing your ADRs next to your source in your source control system. I can recommend this approach, because it gives you all the tooling to manage your changes, e.g. version history, pull requests for reviews, and keeping them in sync with your code …..
However, I can also recommend not using source control if you are using another documentation system such as Confluence, a markdown based wiki or even OneNote.
In my current project, Confluence is our system of choice for documenting system-wide information and we currently store ADRs relevant to more than one team there. We are currently discussing moving ADRs that are now at the team level to live next to the source code with all the impact of distributed documentation.
In the end it really depends on your organization’s documentation strategy and architecture, and you should consider where to store this kind of information carefully. You may want to discuss with your colleagues to see where they would look for this type of information to get a better idea of where it belongs.
If you are going the source control route, there are several tools you can use, like adr-tools by Michael Nygard, a command-line tool for managing ADRs. Kevin Jalbert has written a great post on how to start using ADRs with ard-tools, which I can recommend you try out.
Now that we know more about ADRs, there are several sites I recommend reading before starting with ADRs in your organization.
Joel Parker Henderson has a great GitHub repository with suggestions for writing good ADRs and example templates.
Another great collection for ADRs and related tools can be found at https://adr.github.io/.
That’s already a lot of resources to read about ADRs. If you want to go even further, I can recommend the following talk by Jonathan Wolski about Using Architecture Decision Records and his experience.
danielthecoder 