Template for documenting Architecture alternatives and decisions

Question

We are putting a process in place where all architecture changes must be documented.

Are there any standard templates for documenting alternatives and decisions?

Answer 1

Depends on how detailed / formal you want to be. In terms of a Decisions Register we'd normally use one doc per area / decision, although recently we've been experimenting with OneNote.

At the very least you want to record (for each option):

• Option Description
• Pros and Cons
• Risks and Issues
• Assumptions and Constraints
• Points of Note

A succinct bullet-point list of pros & cons (etc) is usually sufficient - it doesn't need to be a big doc.

For a more in-depth / formal / complex scenario you'd want to go further, this is the format we were using in such cases:

Summary

• Problem Definition
• Solution Context
• Assumptions
• Constraints

Evaluation Criteria

(This is important as it sets out the criteria you used to score the available options, including weightings etc).

Summary of Recommendations

• Summary
• High-Level Comparison Table (This is good for providing an "at a glance" comparison for people who don't want to read a long document; and having a side-by-side comparison is a good idea anyway).

[Option 1…N]

• Option Description
• Pros and Cons
• Risks and Issues
• Assumptions and Constraints
• Points of Note

Recommendation