Architecture documentation and decision records
Wardley Mapping turns build vs buy debates into a reviewable text file. Draw a Wardley map as code, mark what blocks change, and keep it beside your ADRs.
The best architecture means nothing if no one listens. Architects are trained to think in systems and abstractions, but the people they need to convince think in stories. Learn how to use a five-act structure, concrete examples, analogies, and audience mapping to turn your technical decisions into narratives that keep stakeholders engaged and get your proposals approved.
The senior developer leaned back in her chair, watching the new hire struggle with the same AI prompt she'd seen three other teammates wrestle with that week. "Try asking it to include error handling and logging," she called across the room. The junior dev nodded, retyped the prompt, and got better results. But tomorrow, someone else would hit the same wall. Again.
A senior architect at a healthcare tech company was presenting their new microservices platform to the executive team. Fifteen minutes in, the CTO interrupted: "Wait, so where does this actually run? Are we talking containers? VMs? Which cloud regions?" The architect pulled up what they thought was their deployment diagram: A tangled mess of boxes, lines, and AWS icons that looked like it had been designed by a caffeinated spider. The CTO squinted at the screen, then at the architect, then back at the screen. "I’ll just... ask the DevOps team later."
The C4 model gives architecture diagrams four levels of zoom, from context down to code. Here is what each level shows and who actually needs to see it.
Architecture Decision Records capture why you chose one option over another. A lightweight ADR template, a worked example, and how to scale the practice.