Skip to content
Software Architecture Guide

Y-Statement

Explanation

Section titled “Explanation”

A Y-Statement is a short template for writing down a decision about a system’s design. Its six sections together form one (rather long) sentence. The letter Y sounds like “why”, which explains the name.

The long form reads like this:

  • In the context of a use case or user story,
  • facing a concern,
  • we decided for an option and neglected other options,
  • to achieve the desired qualities or consequences,
  • accepting the downside or undesired consequences.

An optional “because” clause can add further rationale.

The first half says what the situation was and what the team chose. The second half says what the choice buys and what it costs. The downside clause makes the trade-off visible. Readers see the price of the decision, not only its benefits.

Where it comes from. Olaf Zimmermann first suggested the WH(Y) template for decision records in a SATURN 2012 presentation. George Fairbanks’s Architecture Haikus inspired it. Projects at ABB have used it, and it has been taught at HSR/OST since 2013. Zimmermann also did joint work with two ABB colleagues on decision guidance (ADMentor).

Compared with other formats. Nygard’s decision records and the arc42 tip each have five sections. Those sections can get rather long. The Y-Statement is the leaner form. Tyree and Akerman’s template is another point of comparison. It drew on the IBM e-business Reference Architecture.

Tool support. ADMentor, an add-in for Enterprise Architect, offers a Y-Statement template for its solution space models and diagrams.

Example

Section titled “Example”

A team builds a web shop. Their statement might read:

In the context of the checkout flow, facing the need to keep each request independent of one server, we decided for keeping session data in a separate session database and neglected storing it on the web servers, to achieve flexible request handling, accepting that the session database must be designed, implemented, and replicated.

The last clause names the cost openly. A later reader can judge whether that cost is still acceptable.

Trade-offs

Section titled “Trade-offs”

The one-sentence form is lean, but it leaves little room. Long reasoning, evidence and option comparisons do not fit in it. The optional “because” clause adds some rationale. Formats with more sections (Nygard’s, the arc42 tip) give more space, but their sections can grow long. The form also only helps if the downside clause is filled in honestly.

The six parts of a Y-Statement, read left to right as one sentence.

Diagram source 
flowchart LR
 A[In the context of] --> B[facing]
 B --> C[we decided for]
 C --> D[and neglected]
 D --> E[to achieve]
 E --> F[accepting that]

Checks

Section titled “Checks”
  • Each decision statement names its context, concern, chosen option, neglected options, desired qualities and accepted downside.
  • The downside clause (‘accepting that…’) states a concrete cost, not a generic remark.
  • The decision is written as one sentence, kept lean.
Section titled “Related”

Sources

Section titled “Sources”