Developing great software architecture doesn’t mean much if it can’t be maintained over time.

Part of maintaining quality architecture requires an understanding of how the current architecture has evolved over time, and what the decisions, assumptions, and constraints at critical points in time.

This can be extremely challenging, as software and supporting teams can change quickly. As team members come and go over time — how do you keep track of decisions that are impactful to your underlying architecture?

This is where Lightweight Architectural Decisions (LADs) can help.

LADs has a simple framework:

  • What is the context around the decision
  • Clarify what is the decision
  • Outlining the consequences/impact of the decision
  • What is current state of the decision

How to implement LADs:

  • Publish a common definition of architecture so there is a shared understanding of when something should be documented
  • Decide where to store LADs — source control, a wiki, a file-share, etc.
  • Create a template to use
  • Define statuses to use (keep it simple)
  • Agree who should be involved with LAD creation/maintenance

Recommended LADs template (by Michael Nygard)

  • Title
  • Context
  • Decision
  • Status (proposed, accepted, deprecated, superseded)
  • Consequences