A good diagram is a deliberate simplification: it shows one aspect of a system at one level of detail for one audience. Teams diagram to agree on scope, to explain designs to newcomers, to review security and data protection, and to think through problems that are hard to hold in your head. Bad diagrams usually mix levels (servers, classes and business steps on one page) or leave out a legend so nobody knows what a box or arrow means.
No single notation covers everything. UML (Unified Modeling Language, standardised by the OMG) is one family with fourteen diagram types for software structure and behaviour. Structured analysis (context diagrams and data flow diagrams) follows data through a system. Entity-relationship diagrams model stored data. BPMN models business processes with roles and events. The C4 model gives a lightweight, zoomable way to show software architecture. Flowcharts remain the simplest way to show logic. And diagrams as code lets you keep any of these as text in version control.
Beginners should start with three questions. Who is the audience? What one question should the diagram answer? What level of detail is right? Then pick the matching diagram below, add a title and a legend, and keep it to what fits on one screen. If a diagram needs a paragraph of caveats, split it into two.
| Question | Diagram | Family |
|---|---|---|
| What is in scope and who interacts with the system? | Context Diagram, C4 System Context | Structured analysis, C4 |
| How does data move and where is it stored? | Data Flow Diagram, Data Dictionary | Structured analysis |
| What are the major services and how do they connect? | Architecture Diagrams, C4 Model | Architecture |
| What are the steps and decisions in this logic? | Flowcharts, Activity | Flowchart, UML |
| Which people and teams do what in a business process? | BPMN | BPMN |
| What can users do with the system? | Use Case | UML |
| Which messages are exchanged, in what order? | Sequence, Communication, Interaction Overview | UML |
| How does one object change state over its life? | State Machine, Timing | UML |
| What classes exist and how are they related? | Class, Object, Package | UML |
| What are the deployable parts and their interfaces? | Component, Composite Structure | UML |
| Which software runs on which hardware? | Deployment | UML |
| What entities are stored and how are they related? | ER Diagram, Logical Data Model | Data modelling |
| How do I keep diagrams versioned with code? | Diagrams as Code | Tooling |