Topical cluster · for Solution architects and senior engineers who own architecture documentation
Architecture Documentation & Diagramming
Architecture work that does not get documented does not get reviewed, does not get inherited, and does not get audited. This cluster covers the documentation craft: diagramming rules that make boxes-and-arrows readable, decision records that survive turnover, and documentation-as-code approaches that stay in sync with the systems they describe.
Articles
1
Coverage spans the 15 rules of perfect architecture-diagram arrows, draw.io patterns for Microsoft and Azure stacks, and the difference between docs that age well and docs that rot in a SharePoint folder.
If you are the architect whose job depends on someone else being able to read your work in three years, start here.
Latest in this cluster
What this cluster covers
Subtopics in architecture documentation & diagramming
- The 15 rules of architecture diagram arrows
- Draw.io patterns for Microsoft and Azure stacks
- Documentation-as-code with Markdown and Mermaid
- Decision records (ADRs) that survive team turnover
- Living documentation in git vs SharePoint Word docs
More in this cluster (0)
The featured article above is currently the only piece in this cluster. More on the way.
Common questions
Architecture Documentation & Diagramming FAQ
The questions that come up most often in architecture documentation & diagramming engagements. Answers grounded in Microsoft documentation and field experience.
Should architecture documentation live in git or SharePoint?
Git, with one exception. Architecture decision records (ADRs), system diagrams (draw.io files committed alongside their PNG exports), API contracts, and runbooks belong in git: they version with the code they describe, get reviewed in pull requests, and stay current because reviewers force them to. SharePoint is acceptable for executive summaries and one-time-share artifacts. Operational documentation in SharePoint rots within 12 months.
What goes in an ADR (architecture decision record)?
Five sections, one page max. Context (the situation that forced a decision). Decision (what was chosen). Alternatives (what was considered and rejected, with reasons). Consequences (what becomes easier and harder). Status (proposed, accepted, superseded). The ADR is not a design document. It captures the why so a future engineer reading the code in three years understands the constraints in play when the decision was made.
Draw.io vs Mermaid vs Excalidraw vs Visio for architecture diagrams?
Draw.io for system architecture (broad shape library, Azure/AWS/GCP stencils, exports to SVG and PNG, free, version-controllable as XML). Mermaid for sequence diagrams and quick flowcharts in markdown that render in GitHub natively. Excalidraw for whiteboard-style sketches in design discussions. Visio only if your org already mandates it. There is no technical reason to choose Visio in 2026.
How do I make architecture diagrams that survive team turnover?
Commit the source file (.drawio XML, .mmd markdown) alongside the rendered image. Generate the image in CI from the source so it cannot drift. Annotate with text (titles, labels, arrow descriptions) instead of relying on visual layout to communicate semantics. Avoid screenshots from whiteboards and Visio diagrams nobody can edit. The 15 rules of arrow design are non-negotiable: directional, labeled, semantically distinct line styles for distinct relationships.
Other clusters
AI Cost & ROI
For ctos.
AI Governance & Risk
For it directors.
AI Strategy & Readiness
For ctos.
AI Architecture
For it directors.
Microsoft Copilot Governance
For it directors.
Copilot Adoption & Recovery
For it directors and execs running copilot programs that are not converting to value.
Power Platform Governance & Operations
For power platform admins.