Introducing Decision Records

You make many Architectural Decisions over its lifetime of a piece of software.

• Redis or memcached?
• HTTP+JSON or GRPC?
• RFC or Slack?
• How does the upload reconciler deduplicate blob artifacts?

If the why behind your choices is documented, it’s slowly lost to time and turnover. Newcomers with fresh eyes have no idea of the business contraints, thinking, or trade-offs analyzed.

“This thing makes no sense?!” - New developer on decade old project

This is where Architectural Decision Records (ADR) come in.

However, I ask: Why just Architectural Decisions for software? Why not Business Decisions? Community Decisions? Social Decisions?

Why not, indeed!

StaffPlus in a community. It’s survives and thrives or withers and dies because of its members. The founders can provide rules, guidance, and guidelines, but they cannot (nor do they want to) be the hall monitors of every interaction. We posit, that for members to self-regulate, they need to understand why the existing rules/guidelines were written.

Thus, Decision Records (DR) were born.

When technical choices, community choices, or code of conduct choices are made, we’ll document them in a Decision Record (DR). The goal of these records is to provide future members with historical context of regarding why things are they way they are. “Because we said so” is no longer enough.

“But where is the Decision Record where we decided to use Decision Records? Why do we have to use them?”

Uh..well..hrm. “Because we said so.”