Skip to content
O'Reilly home
Learning Path

Software Architecture Fundamentals—Diagramming and Documenting Architecture

Time to complete: 1h 51m

Published byO'Reilly Media, Inc.

CreatedJanuary 2020

The underlying architecture for a modern enterprise-scale application can be mind-bogglingly complex to conceive and design. But no matter what your experience level or training might be and how well you understand the labyrinth of components, elements, frameworks, and platforms that comprise your design, one fact remains immutable: many other people will have a vested interest in the architecture you’re planning to create—from stakeholders to developers to SREs, and many more people—and they’re going to need documentation to guide and explain the lay of the land. Indeed, before the project even gets a green light, you’ll need to document architectural decisions and present your rationale to the project’s stakeholders before the first line of code is even written.

In this learning path, the third in a series of six on software architecture fundamentals, your hosts, Neal Ford and Mark Richards, show you effective techniques for diagramming and documenting software architecture. You will also learn how to craft and write successful proposals, business cases, evaluations, and other documentation to support your vision. And, you’ll explore how to document architecture decisions using architecture decision records and effectively justify and communicate an architecture to various stakeholders with clarity and confidence.

What you’ll learn—and how you can apply it

  • Validate, document, and communicate your architecture decisions to the appropriate stakeholders
  • Understand the difference between architecture decisions and technology decisions
  • Make effective technical presentations and learn how to present them
  • Write proposals, evaluations, business cases, and other persuasive documents

Exercises included

  • Guided Exercise: Diagramming Software Architecture
  • Self-Paced Exercise: Diagramming Software Architecture
  • Guided Exercise: Documenting Software Architecture
  • Self-Paced Exercise: Documenting Software Architecture

This learning path is for you because…

  • You’re a senior-level developer who wants to become a software architect
  • You’re junior architect and you want to bump up your skill sets


  • You should have knowledge of development workflows and programming experience

Materials or downloads needed in advance: None

Other learning paths in this series: