Software Design Runs Through Every Layer

▶ Watch (02:55)

Ask a room full of engineers what software design means and you get a hundred answers. Some say code layout, some say UX. Jacqui Read’s definition is broader: design happens at every level, from enterprise context down through architecture and into engineering. Skipping it under deadline pressure is how the gaps appear.

The ACE model she developed puts context first at each layer: regulations at the enterprise level, team policies at the team level. The layers are not sequential phases but vertical slices. Do enough design to move to architecture, enough architecture to move to engineering, then ship.

Decision Records Are a Conversation Tool

▶ Watch (08:14)

An architecture decision record captures why a decision was made. That record lets a team revisit it later: confirm the reasoning still holds, or supersede it when context has changed. Without it, the same question resurfaces and teams spend days re-litigating settled ground.

“the etymology of decide is about cutting off. It’s it’s literally a cut.” — Simon Rohrer

The conversation producing the record matters as much as the document. At Saxo Bank, Rohrer pushes ADRs from enterprise-level down to individual teams, framing the role as facilitation, not pronouncement. Marking a record “draft” rather than “proposed” gets more stakeholder contribution before a decision closes.

Making ADRs Stick Across an Organization

▶ Watch (19:01)

ADR adoption collapses when records land somewhere people never open. Jacqui Read’s rule: match the location to the scope. Repo-level decisions belong in the repo. Cross-team decisions belong in whatever wiki that audience already uses, whether Confluence, Notion, or SharePoint. Don’t create a new place to ignore.

Anchor ADRs to existing rhythms: mention open ones in retrospectives or showcases, and work them into onboarding so new engineers know which records to read first. Rohrer adds a “front door” index pointing to decisions by project, so teams can find the right level without reading everything.

Architect Scope and When to Standardize

▶ Watch (29:43)

Architects know a little about a lot, so developers usually know more about any specific implementation call. Read argues architects should decide at their level and push the rest down. Rohrer calls this “habitability”: an architectural decision sets conditions developers live with for 9 to 12 months, so co-creating beats handing down. Standardizing raises the cost of changing your mind. Newman’s test: if you reversed the decision next week with minimal effort, skip the ceremony. Where reversal is expensive, spend time now. Platform engineering locks in the standards worth keeping so developers focus creativity on the business problem.

Keeping Docs Current and Closing Feedback Loops

▶ Watch (34:47)

Documentation drifts fastest at the detail level. Read’s fix: document only as deep as people actually need, then automate the rest. API docs that change daily belong in OpenAPI, not prose. When someone asks the same question twice, don’t answer it in Slack.

“Give them a link to the answer. If the answer doesn’t exist, create it. Give them a link.” — Jacqui Read

“If the code and documentation disagree, both of them are wrong.” — Sam Newman

For feedback loops, Rohrer treats enterprise architecture as DevOps at scale. Observability tools tell you whether a decision held up in production. Talking to the developers living with it tells you the rest. Decisions that only flow down and never return generate the loudest complaints from the engineers at the bottom.

Q&A

Several teams tried ADRs but they never became the source of truth. Any tips to seed that? Put records where people already work, at the level of scope they affect, and mention open ADRs in existing meetings like retrospectives and showcases. ▶ 19:01

As an engineer transitioning to architect, how do you bridge the detail gap when presenting a first draft to multiple teams? Communicate the desired outcome, not implementation specifics, and let the teams with the right knowledge make the lower-level calls themselves. ▶ 29:43

Code and documents can’t keep pace as services change. How do you mitigate that? Document only as deep as needed, automate anything that changes frequently (such as API docs via OpenAPI), and answer repeated questions with a link rather than a reply. ▶ 34:47

How do you establish feedback loops after a decision is made as new facts emerge? Rohrer treats enterprise architecture as a feedback loop — observability tools show whether decisions held up in production, and talking directly to developers covers the rest. ▶ 42:20

Notable Quotes

you’ve only communicated it enough when somebody you’ve never even met is telling you what’s supposed to be going on Simon Rohrer · ▶ 7:30

the etymology of decide is about cutting off. It’s it’s literally a cut. Simon Rohrer · ▶ 10:32

Give them a link to the answer. If the answer doesn’t exist, create it. Give them a link. Jacqui Read · ▶ 36:40

If the code and documentation disagree, both of them are wrong. Sam Newman · ▶ 37:00

Key Takeaways

  • Document why a decision was made, not just what — the recorded reasoning is what lets teams revisit and override it later.
  • Put decision records where people already work, at the level of scope they affect, or they will be ignored.
  • Architects decide at their level and push the rest down — standardizing forces higher change costs, so weigh that before committing.