Artifact catalog
Several notations often answer the same question; choosing between them is itself a decision.
Does it behave correctly?
- Test suite listed code
How do components and nodes fit together?
- UML component / deployment diagram listed plantuml
How do the parts of a physical system fit together?
- SysML block diagram listed sysml
How do the parts of a system fit together?
- C4 diagrams listed mermaid, structurizr-dsl
How does information flow, and where is it trusted?
- Data-flow diagram listed mermaid, drawio
What concepts exist and how do they relate?
- UML class diagram / domain model listed mermaid, plantuml
What data exists and how does it relate?
- Entity-relationship diagram listed mermaid, dbml
What does the physical thing look like and fit into?
- Drawings / CAD listed dwg, step
What happens, in what order, and who does it?
- BPMN diagram listed bpmn, svg
- Flowchart / swimlane listed mermaid, svg
What happens, in what order?
- UML activity diagram listed mermaid, plantuml
What is each room for, who uses it, and how much space does that intent require?
- Space programme (room schedule) listed csv, markdown
What is the building, as one model all trades share?
- BIM model listed ifc
What is the contract between two physical subsystems?
- Interface control document listed markdown, pdf
What is the contract of an event or message interface?
- AsyncAPI contract listed yaml
What is the contract of an HTTP API?
- OpenAPI contract listed yaml, json
What is the whole architecture, in a standard outline?
- arc42 architecture document listed markdown
What must be true of this system, and why?
- Specification document listed markdown
What must the system do, in stakeholder language?
- BDD scenarios listed feature
What shape must this data have?
- JSON Schema listed json
What states can a thing be in, and how does it move between them?
- State machine diagram listed mermaid, scxml
Which requirement is verified how?
- Verification matrix listed markdown, csv
Who talks to whom, when?
- Sequence diagram listed mermaid, plantuml
Why did we decide this, in one sentence?
- Y-statement listed markdown
Why did we decide this, which options did we reject, and what did we give up?
- Architecture decision record (MADR) listed markdown
Why did we decide this?
- ADR (Nygard) listed markdown