Unit 9: Design & Documentation
Learning Objectives
- Apply documentation principles to UML models for different audiences
- Articulate design rationale — explaining why decisions were made, not just what was decided
- Produce a concise design narrative that walks a reader through an integrated model
Core Input
Read through each tab before working through the key concepts.
A technically correct UML diagram that no one can read is not useful. Good documentation has four properties:
- Clear naming — every class, operation, use case, and attribute has a name that communicates its purpose without explanation. If you need a footnote to explain what DataHandler does, rename it.
- Consistent abstraction — all elements in a diagram operate at the same level of detail. Mixing high-level concepts with implementation details creates confusion. A use case diagram should not include database table names.
- Selective annotation — add notes only where the diagram is ambiguous or where a decision is non-obvious. Annotating everything creates noise; annotating nothing leaves readers guessing about important choices.
- Purpose-driven selection — choose the diagram type that answers the specific question you are trying to communicate. Not every design decision requires every type of diagram.
Different stakeholders need different things from your documentation. The same model can be presented differently depending on who is reading it:
- Executives / clients — care about what the system does and for whom. Use case diagrams are ideal: goal-focused, no technical notation, readable by anyone.
- Business analysts / domain experts — care about processes and workflows. Activity diagrams (especially with swimlanes) show responsibilities clearly.
- Developers — care about structure and interaction detail. Class diagrams (with full notation) and sequence diagrams (with operation signatures).
- Testers — care about what conditions trigger what behaviour. Activity diagrams (to derive test paths) and sequence diagrams (to verify message flows).
Producing one version of a diagram "for everyone" often means it works well for no one. Tailor your presentation to its audience.
Design rationale is documentation that explains why a decision was made — not just what was decided. It includes:
- The options that were considered
- The criteria used to evaluate them (performance, simplicity, testability, etc.)
- The trade-offs that were accepted
- The option that was chosen and why
Example: "We chose composition over aggregation for the Order–OrderLine relationship because OrderLine objects have no meaning outside of an Order. This simplifies the data model and enforces referential integrity. The trade-off is that OrderLine objects cannot be independently archived, which was accepted since the client has no archiving requirement."
Without rationale, future maintainers may unknowingly revisit decisions already made — wasting time or reintroducing rejected approaches.
Key Concepts: Documentation Principles
Work through each item. Good documentation is a skill, not an afterthought.
A clear name communicates purpose without ambiguity. Tests for a good name:
- Can a developer who did not write the model understand it immediately?
- Does it describe what the element is or does, not how it works?
- Is it specific enough to distinguish it from similar elements?
Common naming problems:
- ✗ DataManager — manages what data? does what with it?
- ✓ StudentEnrolmentService — clear scope and purpose
- ✗ processData() — processes which data, into what?
- ✓ calculateFinalGrade(assessments : List) : Grade — specific and complete
In UML, names appear on diagrams consumed by many people over many months. A bad name is a small cost at the time of writing and a large cost at every subsequent reading.
A diagram at a consistent level of abstraction contains elements that all belong at the same conceptual altitude. Mixing levels creates a disorienting diagram that is hard to reason about.
Example of inconsistent abstraction in a class diagram:
Student— a meaningful domain conceptCourse— a meaningful domain conceptdb_connection_pool— an implementation detail (belongs in a deployment or component diagram)EmailValidator— a utility class that belongs at a lower level of the architecture
The fix is not to remove these elements from the model — it is to put them in the right diagram, at the right level, for the right audience.
Annotations (UML notes are shown as dog-eared rectangles) should be used selectively:
- Add a note when: a decision is non-obvious, a constraint cannot be expressed in standard notation, or a diagram element would be misunderstood without context.
- Do not add a note when: the element name already communicates the point, or the note would repeat what the diagram already shows.
Over-annotation is as unhelpful as under-annotation — it forces the reader to read a wall of text attached to every element. Reserve annotations for genuinely non-obvious points.
Good documentation has boundaries. Things that do not belong in UML model documentation:
- Implementation code — operation bodies, SQL queries, algorithms. These belong in the source code, not the model.
- Meeting notes and draft commentary — the model should represent agreed decisions, not the discussion that led to them.
- Stale information — outdated diagrams that no longer represent the system are worse than no documentation, because they actively mislead.
- Redundant description — prose that simply restates what the diagram already shows. Documentation should add to the diagram, not repeat it.
Key Concepts: Audience and Rationale
Understanding your audience and capturing your reasoning are two of the most transferable skills in professional software engineering.
The diagram type you choose should match what your audience needs to understand, not what you find easiest to produce.
| Audience | Need | Best diagram type |
|---|---|---|
| Client / executive | What does the system do? | Use case diagram |
| Business analyst | How does the process work? | Activity diagram (with swimlanes) |
| Developer | What classes exist and how do they relate? | Class diagram |
| Developer | How is this feature implemented? | Sequence diagram |
| Tester | What are the test scenarios? | Activity diagram, sequence diagram |
Design rationale captures the reasoning behind a decision — the alternatives considered, the trade-offs evaluated, and the justification for the chosen option.
Without rationale, a model is a record of what was decided. With rationale, it is also a record of why — which is far more valuable when the system must evolve.
Rationale prevents knowledge loss: when the original designer leaves, the reasons for key decisions go with them. Future maintainers then face the choice of trusting a decision they do not understand or rediscovering the answer at significant cost.
A rationale entry should be concise but complete. A useful template:
- Decision: What was decided?
- Options considered: What alternatives were evaluated?
- Criteria: What factors mattered (performance, simplicity, cost, risk)?
- Justification: Why was this option chosen over the others?
- Trade-offs accepted: What was given up by making this choice?
Rationale does not need to be long — two or three sentences per decision is usually enough. The goal is to give a future reader enough context to understand the choice, not to reproduce the entire design discussion.
A diagram description restates what the diagram shows: "The Student class has a name attribute and an enrol operation."
A design narrative guides a reader through the model, explaining the structure, the key decisions, and how the pieces connect: "The central relationship in the model is between Student and Course. We chose a many-to-many association here because our requirements specify that students can enrol in multiple courses and each course has multiple students. The Enrolment class acts as the associative class, holding the enrolment date and grade — data that belongs to the relationship itself, not to either participant."
A narrative adds interpretation. It tells the reader not just what exists, but what matters and why it was designed that way.
Watch
Video coming soon
Check Your Understanding
Select the best answer for each question.
A non-technical project manager needs to understand what a software system does and for whom. Which UML diagram is most appropriate?
Design rationale documentation should primarily answer which question?
Activities
Individual task
Choose one diagram from your integrated model (Unit 8) — ideally one that contains a design decision you remember discussing.
Review it against these criteria and make improvements:
- Names: Rename any class, operation, or use case that requires explanation to understand. The new name should make the purpose self-evident.
- Abstraction level: Remove any element that belongs at a different level. Add a note if a decision is non-obvious.
- Audience: If this diagram were shown to a non-technical stakeholder, what would confuse them? Address it.
Pair task — structured peer review
Exchange your revised diagram with a partner. Review it against these four questions:
- Are all names self-explanatory to someone unfamiliar with the project?
- Is the level of abstraction consistent throughout — or does any element feel out of place?
- Is there any design decision on the diagram that is left unexplained?
- If you had to describe this diagram in one sentence, could you?
Provide written feedback on at least two specific improvements, citing the element and explaining why the change would help.
Group task
As a group, produce a design narrative for your integrated model from Unit 8.
The narrative should be 200–300 words and cover:
- The purpose of the system (one sentence)
- The key structural decisions in the class diagram (most important relationships, any use of inheritance or composition) with brief rationale
- How the main use cases are implemented (sequence or activity diagram highlights)
- At least one design trade-off that was consciously made
Write it as if you are handing the model to a new developer joining the project on their first day. What do they most need to understand quickly?
Review
- Match the diagram type to the audience's question — not to your preference
- Use case diagrams for non-technical stakeholders; class and sequence diagrams for developers
- Use names that communicate purpose without explanation
- Maintain consistent abstraction within a single diagram
- Annotate selectively — only where genuine ambiguity exists
Describing restates what is in the diagram: "The Order class has an OrderLine collection."
Explaining adds interpretation: "OrderLine is modelled as a composition rather than an attribute list because it represents a distinct domain concept with its own quantity and price — and because future requirements may add behaviour to individual order lines."
Explanation requires understanding. It is the mark of a designer who knows not just what they built, but why it is the right thing to build.
Proceed to Unit 10: Critical Analysis when ready.