Choose the diagram question
A diagram must answer a question. Architecture shows parts and relationships; a sequence shows who does what over time; a flow highlights steps and decisions; a state machine describes allowed situations and transitions.
Don’t put all of these goals into a single diagram. To explain a service interaction, start with the request flow. To investigate a delay, a sequence between customer, application, and storage may be more appropriate. The choice determines what’s included and what’s left out.
Why learn
A beautiful diagram with a confusing purpose doesn’t help you decide. A clear question lets you assess whether the diagram explained the problem or merely reorganized words.
✓ Do
Show the error path.
✗ Avoid
Draw components just because they are common.
Key concepts
List only confirmed elements
Before drawing, list participants, inputs, outputs, and the places where the data is stored. Link each element to a project evidence or to an identified hypothesis. If you don’t yet know where a file is saved, don’t draw a database out of habit.
Use names the audience recognizes. “Reception,” “order list,” and “check” can explain a business process better than internal function names. When a technical name is needed, also present its function in plain language.
Why learn
The list prevents the assistant from completing the architecture with plausible but nonexistent components. It also establishes vocabulary that you can review before changing the diagram.
A way to apply
- Define the question and list the confirmed elements.
- Draw relationships using verbs and decisions.
- Go through two cases and adjust readability.
Key concepts
Give meaning to connections
A line between boxes can mean sending, reading, dependency, or order. Label the connection when that isn’t obvious. Use the same convention across the diagram and include a short legend when there’s more than one type.
In the example, “validate” isn’t the same as “save.” The check can reject an order before it enters the list. Showing this decision prevents the reader from thinking that every entry is accepted. The error path deserves as much clarity as the happy path.
Why learn
Connections carry much of the meaning. Without labels and decisions, the reader may infer causality where there is only a query relationship.
flowchart TD
A[Receber pedido] --> B{Tarefa e contato presentes?}
B -- Sim --> C[Registrar na lista]
B -- Não --> D[Pedir complemento]
D --> A
C --> E[Conferir entrega]
E --> F[Concluir]
Key concepts
Keep an editable source
Save the diagram in a format that allows changes, in addition to the presentation image. A Mermaid description, an SVG, or the tool’s native file can serve as the maintenance base. A PNG alone is useful for showing, but it’s a hassle to fix.
Record the version of the process represented. If a step changes, check which connections no longer make sense. Don’t update only the box name: the change may require a new path, a validation, or an intermediate state.
Why learn
An editable source reduces the cost of keeping documentation aligned with the system. It also makes it possible to review the diagram as part of a code change.
✓ Do
Save the editable file alongside the image.
✗ Avoid
Use an arrow without knowing what it means.
Key concepts
Test someone else’s understanding
Ask someone to walk through one normal case and another with an error using only the diagram. Notice where the person needs to guess. A small arrow, an abstract name, or a missing step often shows up during this reading.
Also do a visual check: readable text, sufficient contrast, and connections without unnecessary crossings. On small screens, prefer a simpler diagram over a huge image scaled down until labels become unreadable.
Why learn
The test measures the map’s communicative function. You check whether the reader understands order and conditions, instead of evaluating only aesthetics.
| Criterion | Expected evidence |
|---|---|
| Fidelity | The diagram matches the prompt. |
| Exception | An incomplete request has an explicit path. |
| Maintenance | There is an editable representation. |
Key concepts
Practice: draw the incomplete request
Represent a request that arrives at the workshop. If it has a task and contact, it goes into the list. If one of those pieces of data is missing, it goes back for completion. After the final check, it can be marked as completed.
Write the flow description, generate the diagram in the tool of your choice, and compare the paths to the prompt. Don’t add payment, artificial intelligence, or a database if those elements aren’t necessary to answer the exercise question.
Why learn
Practice teaches you to contain the diagram’s scope and represent exceptions. The result will be reused in the documentation of the final projects.
Your exercise
Create a flow for the order described in the topic. Identify the decision, the return, and the output. Explain how the diagram behaves when the contact is missing.
Download practice sheetCheck the commented answer
Decision: are the task and contact present? If not, ask for completion and return to receiving. If yes, register, check the delivery, and conclude. Missing contact prevents moving on to registration, without deleting the received request. The image and its source must show the same path.
Check your understanding
You don’t know where the system stores data. How should you represent that?
Key concepts
What stays from this module
An editable flow map accompanied by a simple explanation.
- ✓ The diagram matches the prompt.
- ✓ The incomplete request has an explicit path.
- ✓ There is an editable representation.
Progress records your reading. The practice is completed when you check the submission.