SA-201c · Module 2

Diagramming Tools & Workflows

3 min read

The best diagramming tool is the one the team will actually use and maintain. A beautiful diagram in a tool nobody uses is a snapshot that will be stale tomorrow. A simple diagram in a tool the team uses daily is documentation that stays current. The tool selection should optimize for maintenance, not creation — because diagrams are created once and maintained for years.

  1. Diagram-as-Code Tools like Mermaid, PlantUML, and Structurizr define diagrams in text that lives in the repository alongside the code. Version-controlled. Diffable. Reviewable in PRs. The trade-off: less visual polish than graphic tools. The benefit: the diagram is maintained with the code because it lives with the code.
  2. Visual Diagramming Tools Tools like Excalidraw, draw.io, and Lucidchart provide visual editing with drag-and-drop. The trade-off: the diagram lives outside the repository (usually) and requires manual export for documentation. The benefit: faster creation for complex layouts and easier collaboration with non-technical stakeholders.
  3. The Hybrid Approach Use diagram-as-code for L1-L3 architecture diagrams that are maintained long-term. Use visual tools for whiteboarding, discovery, and stakeholder presentations that are ephemeral. The distinction: if the diagram needs to stay current for months, it should be code. If it needs to communicate once, it can be visual.

Do This

  • Select tools based on maintenance workflow, not creation speed — diagrams are maintained longer than they are created
  • Use diagram-as-code for long-lived architecture documentation — version control prevents drift
  • Store diagram sources in the repository alongside the code they document

Avoid This

  • Choose the most feature-rich tool without considering whether the team will maintain it
  • Store diagrams only in a presentation deck — decks are ephemeral, architecture documentation is not
  • Manually redraw diagrams with every change — if the diagram cannot be updated programmatically, it will not be updated