If you write software, you need to start maintaining Architecture Decision Records (ADRs). ADRs roughly fall into the category of Developer Documentation. They aren't aimed at the Users of the software. Instead, they are aimed at the developers and maintainers of the software. They usually contain information about the layout of the package and what the code does. ADRs, in this context, are an absolute necessity. By definition, ADRs are simply a Record of a Decision that has an impact of the Architecture of the application. In fact, Any meaningful technical decision made in a software project, irrespective of whether it has an impact on the architecture of the application, needs to be documented. I first came across ADRs in Chapter 17 of Fundamentals of Software Architecture book. A few of us (at Enthought ) read this book earlier in the year and ADRs are one of the things that we took away from the book. You can find more information on ADRs here and here . Here's what the f...