Architecture Decision Logs

I recently discovered “Architecture Decision Logs” or Architecture Decision Records (ADL/ADR) in a software project and really like the idea of explicitly writing down such decisions. You can find complex templates, theory and process for these documents that might be appropriate for big projects. For a small project I don’t think that these are necessary and a free-form text file is probably fine.

Besides benefits of an ADL listed elsewhere, I also see benefits especially for free software projects:

• Potential contributers can quickly decide whether they want to align with the decisions.
• Discussions about project directions can be handled with less emotions.
• A decision to fork a project can be based on diverging architecture decisions.
• Potential users can decide whether the software aligns with their needs.
• Code readers might have less WTF moments in which they believe the code author was stupid, incompetent and out of their mind.

The purpose of ADLs overlap with Project Requirements and Design documents (PRD, DD). While the latter should in theory be written before coding starts, ADLs are written during the development of the project and capture the thought process.

Thus ADLs are in my opinion more aligned with the reality of (agile) software development while PRDs and DDs are more aligned with hierarchic organizations in which development is driven by management decisions. As a consequence PRDs and DDs often don’t have much in common with the real software or hinder the development process since programmers feel pressured not to deviate from them.