Changelogs, Captain's Logs, and Architecture Decision Records

Image of Author
March 5, 2023 (last updated May 14, 2023)

ADRs

The opening lines of https://adr.github.io/ give a good technical intro to the topic

An Architectural Decision (AD) is a justified software design choice that addresses a functional or non-functional requirement that is architecturally significant. An Architecturally Significant Requirement (ASR) is a requirement that has a measurable effect on a software system’s architecture and quality. An Architectural Decision Record (ADR) captures a single AD and its rationale; the collection of ADRs created and maintained in a project constitute its decision log. All these are within the topic of Architectural Knowledge Management (AKM), but ADR usage can be extended to design and other decisions (“any decision record”).

These can end up being sophisticated in terms of both document details and system management. There are examples of minimalist templates, for example this one by Joel Park Henderson

Captain's Log

An even more minimal version is a Captain's Log. A Captain's Log is a history of thoughts and decisions made by maintainers of a software project.

This is so minimal it is almost redundant with the git log. But a git log is fit for a different purpose, and trying to get from it a narrative sense of the architectural and decision history of a project can be difficult.

A simple example of a Captain's Log is a list of bullet points in a README.md file. Each bullet point can be dated, and a few sentences can be written to discuss important decisions made. For example, if a particular solution was weighed against others, you can write what were considered the pros and cons of each option. If there was a pivot in the conceptual identity of the project, that can be noted, as well as why the pivot was made. Why you chose to, or, to not, support a particular feature can be documented. These types of documentation can be a good reference point in the future for when these topics resurface and people don't remember previous decisions.

As a Captain's Log grows in size, you can move it to a separate file, e.g., CAPTAINS_LOG.md. But doing so begins to bleed into yet another change management strategy, a change log.

Changelog

A Changelog tracks changes to a repository over time. It is common to see in open-source projects, often doubling as release notes. As such it is focused more on users of the software than developers of the software.

When to use a particular log

Developers are concerned with architectural and decision history, while users are concerned with changes in external-facing APIs. But, there is overlap, and what kind of information is useful to particular parties is contextual.

If the reader is a user, consider a changelog. If the reader is a dev, consider a captain's log and/or ADR.