Sequence, class, state, ERD, activity: the workhorses.
The diagram types most engineers already half-know. Sequence and state diagrams are the two that repay the effort most often, because both describe things prose is genuinely bad at: interleaving over time, and the set of legal transitions.
Sequence diagrams grow horizontally without limit and become unreadable somewhere around eight participants. If yours has more, it is usually two diagrams: the happy path, and the failure handling.
State diagrams are worth drawing precisely because they force you to answer "what happens if this arrives twice?", a question that rarely gets asked in prose.
The highest-value diagram in this list. Time runs down; participants across.
@startuml
title Sequence Diagram
actor User as U
participant "Web App" as W
participant "API" as A
database "Database" as D
U -> W: Request
activate W
W -> A: API Call
activate A
A -> D: Query
activate D
D --> A: Results
deactivate D
A --> W: Response
deactivate A
W --> U: DisplayEarns its place when there are real branches and joins.
@startuml
title Activity Diagram
start
:Initialize;
if (Condition?) then (yes)
:Action A;
:Action B;
else (no)
:Action C;
endif
fork
:Parallel Task 1;
fork again
:Parallel Task 2;
end fork
:Final Step;
stopActor-to-goal. Dated, but still the clearest way to show scope boundaries.
@startuml
title Use Case Diagram
left to right direction
actor "User" as user
actor "Admin" as admin
rectangle "System" {
usecase "Login" as UC1
usecase "View Dashboard" as UC2
usecase "Manage Users" as UC3
usecase "Generate Report" as UC4
}
user --> UC1
user --> UC2
user --> UC4
admin --> UC1
admin --> UC3
UC3 ..> UC1 : <<include>>
Best used for a single bounded context, not a codebase.
@startuml
title Class Diagram
abstract class Animal {
- name: String
- age: int
+ getName(): String
+ makeSound(): void
}
class Dog extends Animal {
- breed: String
+ fetch(): void
+ makeSound(): void
}
class Cat extends Animal {
- indoor: boolean
+ scratch(): void
+ makeSound(): void
}
interface Trainable {Forces the awkward questions about duplicate and out-of-order events.
@startuml
title State Diagram
[*] --> Idle
state Idle {
[*] --> Waiting
Waiting --> Waiting : timeout
}
Idle --> Processing : start
Processing --> Success : complete
Processing --> Error : fail
Success --> Idle : reset
Error --> Idle : reset
Error --> Processing : retry
Success --> [*]
@endumlCardinality is the part people get wrong. Write it explicitly.
@startuml
title Entity Relationship Diagram
entity "User" as user {
* id : INT <<PK>>
--
* email : VARCHAR(255)
* password_hash : VARCHAR(255)
created_at : TIMESTAMP
}
entity "Post" as post {
* id : INT <<PK>>
--
* user_id : INT <<FK>>
* title : VARCHAR(255)
content : TEXT
published : BOOLEAN
created_at : TIMESTAMP
}
entity "Comment" as comment {
* id : INT <<PK>>For structuring thinking, not for documenting a system.
@startmindmap
title Mind Map
* Project
** Planning
*** Requirements
*** Timeline
*** Resources
** Development
*** Frontend
**** Components
**** Styling
*** Backend
**** API
**** Database
** Testing
*** Unit Tests
*** Integration Tests
** Deployment
*** Staging
*** Production
@endmindmapPlans, not architecture, but it renders from text, so it diffs in review.
@startgantt
title Project Timeline
Project starts 2024-01-01
[Planning] lasts 10 days
[Design] lasts 15 days
[Design] starts at [Planning]'s end
[Development] lasts 30 days
[Development] starts at [Design]'s end
[Testing] lasts 15 days
[Testing] starts at [Development]'s end
[Deployment] lasts 5 days
[Deployment] starts at [Testing]'s end
@endganttVisualises a JSON payload: handy in an API design review.
@startjson
title JSON Data Structure
{
"user": {
"id": 1,
"name": "John Doe",
"email": "[email protected]",
"roles": ["admin", "user"],
"settings": {
"theme": "dark",
"notifications": true
}
}
}
@endjsonWork breakdown. Useful for scoping a piece of delivery.
@startwbs
title Work Breakdown Structure
* Project
** Phase 1: Planning
*** Define Scope
*** Identify Stakeholders
*** Create Timeline
** Phase 2: Execution
*** Task 1
**** Subtask 1.1
**** Subtask 1.2
*** Task 2
*** Task 3
** Phase 3: Closure
*** Documentation
*** Handover
@endwbsEvery template here ships in Gnomon and renders on your machine, with no account and nothing sent to a server. The browser editor is free and needs no install.