Personal Configuration Records

Inspired by Architecture Decision Records (ADRs), I have started keeping a written log of configuration changes I make to my home computers. I call these Personal Configuration Records (PCRs).

The idea is the same: To keep a record of “significant” configuration decisions and why I made them.

The format is simple: a series of text files, numbered in chronological order. (I use Org Mode, because I’m like that.) Each file has the following sections:

• Context: What I was trying to do and why.
• Decision: A brief description of what I did.
• Changes Applied: A log of the shell commands I ran and files I edited.
• References: Links to documentation or tutorials that I used.

Sometimes I add additional notes describing how to use or verify the configuration I just created.

If I had more than a handful of computers, I would doubtless benefit from more sophisticated provisioning tools that support reproducible builds. But I don’t have that many computers at home, and each one serves a distinct purpose, so it’s rare that I would repeat the same configuration on more than one machine.

On the other hand, it may be months or years before I need to modify that configuration. I am not likely to remember the details of what I did. Even in just a few weeks, as I set up a new home server, this method has helped me recall what I did and why.