Architectural Decisions

"Architecture represents the significant design decisions that shape a system,
where significant is measured by cost of change."

-- Grady Booch

In real architecture it is obvious, when thee foundation is completed and the stories of your building rise, there's no way to swap out the foundations without demolition and starting over.

In software architecture it is less obvious, but nevertheless similar important not to send in the demolition crew half way into delivery.

While in construction you demolition crew easily can be identified by hard hats, orange vests and heavy machinery, your software demolition crew often comes disguised as concerned stakeholder questioning fundamental decisions over and over (out of a variety of motives). So it is paramount to document your archtectural decisions well.

Decisions, Justification, Alternatives, Impact

Our typical architecture decision documentation starts, duh, with the table of content (unless that sits in a sidebar) and an overview of your architecture. One or more diagrams to provide an overview are well placed here.

Now number the decisions, so they can be refered to by their shortform (e.g AD45) rather than their full title. For larger or delicate system, you want to place each decision on their own page, not at least to be able to extract one (as PDF) for customer sign up. While it is tempting to use a word processor, I'd argue to use an engineering format like markdown or, when complexity justifies it, DITA. Document format and storage could be considered primordial architectural decisions.

Each decision needs to provide four elements:

1. Decision
   What have you decided. A factual statement. Something along the line "Our choosen programming language is COBOL"
2. Justification
   Outline why. It should cover features, cost, skills. You don't need to state why the alternative failed in your considerations
3. Alternatives
   What have you looked at, what made you reject the alternative possibiliy. We need to be careful, analysis paralysis lurks here. There is always another framework, language or database you could consider. This is also the area where our "friendly" demolition crew will try to stall us
4. Impact
   Serves are a reinforcement of Justification, but extends, when appropriate, on potential risk and its mitigation. It is an important section, nevertheless our "Reichsbedenkenträger" (loosely translated as "Imperial wardens of concern") lurk here. So stay concise to the point. You don't write a PHD thesis here.

Depending on the impact of the system (malefunktion threatens life, threatens assets or requires to hit reload in the browser) you need to spend more or less time on it. For a refresher on this concepts, have a look at Crystal Clear page xvi in the preface.

Where to store them?

The best documented decisions are useless when nobody find them. So somewhere in OneDrive, Sharepoint or Jira, they most likely they are lost.

We want to keep them close. I use 2 places, depending on the project. In maven based projects, the Maven Site Plugin allows to store the entire documentation, written in markdown, in /src/main/site (supports other formats too), while in other projects the /docs folder will do. GitHub pages and the Just-the-docs skin render them nicely.

In other words: Our documentation lives inside the source repository

Signoff

It gets a little tricker when decisions need to be signed off. In the traditional approach that would be a word document, printed out and signed with a pen (shudder).

A more modern approach would be digitally signed PDF documents (real digital signatures, not the fancy PDF graphics).

Both solutions are wanting in storage and findability (Sharepoint anyone?), so I'd rather recommend a professional solution. This doesn't preclude your living document to stay in your version control system

As usual YMMV