DevSecOps Engineer, Author, and Mentor

While working on my upcoming book, Getting Started with Architecture Decision Records (ADRs), I demonstrated Nat Pryce’s adr-tools tooling. Nat’s tool is truly excellent and I’ve been using it for years. It’s a Bash shell script that can be used to quickly create and maintain ADRs in a Git repository.

As my needs evolved, I found a little place here and another place there where adr-tools didn’t quite align with my needs. For example, adr-tools has a shell script driver plus a bunch of libraries for individual commands. Don’t get me wrong, I love a modular, extensible approach! On the other hand, it meant having to clone or track a small repository of files, not just a single script.

The filenames adr-tools used for ADRs worked well until I encountered a project whose naming convention conflicted with them.

So, a new tool was born: adrctl!

Read More

Few phrases frustrate me as much as, “Because that’s how we’ve always done it.”

The phrase sounds like an explanation, although it provides no reasoning. It asks the listener to accept a practice because the practice already exists. The people who made the original decision may be gone. The conditions that shaped it may have changed. The risks, constraints, conversations, and rejected alternatives may have disappeared from memory. All that remains is the conclusion.

That is how a decision becomes a tradition.

The problem is not that old decisions are necessarily wrong. Many were thoughtful responses to difficult circumstances. The problem is that a future team may inherit the action without inheriting the reasoning. Once that happens, the organization no longer knows whether it is preserving a wise safeguard, repeating an obsolete compromise, or following a habit whose purpose disappeared years ago.

An Architecture Decision Record, commonly called an ADR, helps prevent that loss.

An ADR captures a decision at the moment it is made. It records what the team knew, what remained uncertain, what constraints mattered, what alternatives were considered, why one option was selected, and what consequences the team anticipated. An ADR preserves enough context for someone in the future to understand the decision as more than an unexplained instruction.

That distinction matters.

Read More

I use a GitHub project to manage household projects and tasks. I wrote about it a few times in the past, such as in how we used scrum to schedule our holidays and in an update on household_scrum. This is a continuation of that project to bring a never-ending TODO list to heel.

User Interfaces

Some people like seeing a shiny, sparkly project board with tasks and stories sorted neatly into columns. Moving cards to the right (i.e., taking a card from todo to in progress to done) brings dopamine hits and dashes of joy as things get done. It’s really a great feeling to take a big, involved task that took hours or days of work and plop it into the “done” column. I think I remember a classic black-and-white movie where they said, “Every time a card is moved to done, a project manager gets its wings.”

Some people don’t want to use a project board. It looks like extra work on an unfamiliar interface. It looks like a waste of time and energy. Why should I play around with a virtual whiteboard when I could be working on my next task? Isn’t maintaining the board someone else’s job?

Read More