Unit 6: UML & Documentation
Learning Objectives
- Select the appropriate UML diagram type for a given documentation purpose
- Create class and component diagrams that accurately reflect an architectural design
- Explain the relationship between models, implementation, and maintenance documentation
- Adapt technical documentation for different audiences, distinguishing between intent and implementation
Core Input
Read through each tab before working through the key concepts.
UML is not a single activity performed at one point in the SDLC — it is a toolkit applied throughout the lifecycle, with different diagram types serving different purposes at different stages.
- Requirements stage — use case diagrams establish system scope; activity diagrams model business workflows
- Design stage — class diagrams define structure; sequence diagrams specify interactions; component and deployment diagrams define the physical architecture
- Implementation — class diagrams guide code structure; sequence diagrams guide API design
- Maintenance & Evolution — existing diagrams serve as documentation for incoming team members; updated diagrams communicate structural changes
A key distinction in this course (building on the UML for Software Engineering course) is between producing diagrams and reasoning with them. The value of UML in the SDLC is not the diagrams themselves — it is the architectural thinking the diagramming process forces, and the communication the diagrams enable.
Class diagram (structural)
At the architectural level, a class diagram does not show every field and method — it shows the major domain entities, their responsibilities, and the relationships between them. The goal is to communicate the domain model and the structural decisions that support it: which classes exist, what they are responsible for, and how they relate.
Component diagram (structural)
A component diagram shows the high-level modules of a system — larger-grained than classes — and the interfaces through which they communicate. It is the primary diagram for documenting a system's architecture: "Here are the major components; here is how they depend on each other; here are the interfaces they expose and consume."
Key elements: components (boxes with a component stereotype or icon), interfaces (provided: lollipop notation; required: socket notation), and dependencies (dashed arrows).
Deployment diagram (structural)
A deployment diagram shows how software is distributed across physical or virtual infrastructure: nodes (servers, containers, devices), artefacts (deployed software components), and communication paths. It answers the question: "Where does each part of the system actually run, and how do the parts communicate across the network?"
Technical documentation serves multiple audiences with different needs. Effective documentation matches its content, depth, and language to its intended reader.
Common documentation types and their audiences:
- Architecture overview (executive summary) — audience: non-technical stakeholders, project sponsors. Content: system purpose, major components in plain language, key constraints. Avoids technical notation.
- Component and deployment diagrams — audience: architects, senior developers, operations. Content: structural relationships, interfaces, infrastructure. Uses UML notation.
- API documentation — audience: developers integrating with the system. Content: endpoints, request/response formats, authentication, error codes. Precise and exhaustive.
- ADRs — audience: current and future engineers. Content: decision context, options, rationale, consequences. Preserved in version control.
- Runbooks / operational documentation — audience: operations team. Content: deployment procedures, rollback instructions, monitoring thresholds, on-call escalation paths.
Documentation that serves no specific reader is documentation that will not be read. The question before writing any document is: who will read this, and what do they need to be able to do after reading it?
Key Concepts: UML Diagram Selection
Knowing which diagram to reach for — and when — is a professional skill. Work through these items to develop that judgement.
Both are structural diagrams, but they operate at different levels of abstraction:
A class diagram models the domain — the entities, their attributes, operations, and relationships. Its granularity is the class or object. A class diagram is most useful during detailed design and as a reference for developers implementing the domain model.
A component diagram models the system's modular structure — the large-grained building blocks (services, modules, libraries) and the interfaces through which they communicate. It does not show class-level detail. Its granularity is the deployable or independently compilable unit. A component diagram is most useful for communicating architecture to technical stakeholders and for planning integration.
Think of it this way: a component diagram shows the walls and doors of a building; a class diagram shows the furniture inside each room.
A deployment diagram becomes necessary when the physical or virtual distribution of the system is non-trivial — when it matters where components run and how they communicate across network boundaries.
It is particularly valuable for:
- Systems distributed across multiple servers, availability zones, or geographic regions
- Systems with external integrations (third-party APIs, legacy systems, NHS Spine)
- Cloud-native or containerised systems where the infrastructure is programmatically defined
- Regulatory or security contexts where data must not cross certain boundaries
For a simple single-server application, a deployment diagram adds little value. For a microservices system with twelve services deployed across three availability zones and integrating with four external APIs, it is essential.
Model-driven design (MDD) is an approach in which the model is the primary artefact — code is generated from or traceable to the model, rather than the model being a post-hoc description of existing code.
In its pure form, MDD uses tools to automatically generate code from UML models. In practice, most teams adopt a weaker version: they treat models as the authoritative specification that code must conform to, and actively maintain the models as the design evolves.
The key principle is that models and code must remain consistent. A model that describes a system that no longer exists — because the code has diverged — is worse than no model at all, because it actively misleads. Maintaining model-code consistency requires discipline and explicit process: when code changes, models must be updated.
Key Concepts: Documentation
Good documentation is written for a specific reader, not for its own sake.
Implementation documentation describes what the code does — method signatures, data formats, call sequences. It is derivable from the code itself (and should be, in well-named codebases). It answers: "What does this function do?"
Intent documentation describes why the system is structured as it is — the design rationale, the constraints that were accepted, and the alternatives that were not chosen. It cannot be derived from the code. It answers: "Why is this structured this way?" and "What would break if I changed it?"
The most valuable and most often missing documentation is intent documentation. ADRs are the primary vehicle for it, but inline comments explaining non-obvious design decisions serve the same purpose at a smaller scale.
The lifespan of a software system typically far exceeds the tenure of the team that built it. Documentation written for the original development team — full of unexplained assumptions and tacit knowledge — becomes increasingly useless as team composition changes.
Good documentation reduces onboarding time for new engineers, reduces the risk of inadvertently breaking undocumented invariants, and enables informed decision-making about evolution and refactoring. Poor documentation — or its absence — is itself a form of technical debt.
A useful test: can a new engineer join the team, read the documentation, and make a meaningful contribution within a reasonable time? If not, the documentation is insufficient — regardless of how well the code itself is written.
- Documentation that describes the obvious — extensive documentation of what the code self-evidently does, with no documentation of why
- Stale documentation — documents written during initial development that were never updated as the system evolved; they actively mislead rather than inform
- Documentation for the wrong audience — written at the wrong level of abstraction; too technical for sponsors, too vague for developers
- Documentation as compliance theatre — produced to satisfy an audit requirement with no intention of it being read or maintained
- Absence of operational documentation — excellent design documentation but no runbooks; when a production incident occurs, no one knows how to respond
Watch
Video coming soon
Check Your Understanding
Select the best answer for each question.
A component diagram that shows a 'PatientService' component with a provided interface 'IAppointmentBooking' and a required interface 'INotificationService' is communicating:
A class diagram produced during the design phase accurately described the system. Two years later, the same diagram is used by a new developer to understand the system. The diagram no longer matches the code. The primary risk is:
AI tools can generate documentation from code — docstrings, README files, API references, and even draft architecture descriptions from a codebase scan.
- Assist: AI is genuinely effective at generating implementation documentation — describing what functions do, what parameters they accept, and what they return. It can also produce draft component descriptions from well-named code, reducing the time cost of documentation that is often deferred indefinitely.
- Risk: AI-generated documentation describes what it observes in the code — it cannot document intent, design rationale, or the constraints that shaped a decision. An AI writing an ADR will produce a plausible-sounding rationale that may not reflect the actual reasoning. ADRs written by AI are fiction that happens to sound like engineering judgment.
- Principle: Use AI for implementation documentation where the content is derivable from code. Intent documentation — ADRs, architectural overviews, design rationale — must be written by the engineers who made the decisions. It records something that only they know: what was considered, what was rejected, and why the cost of this choice was judged acceptable at the time.
Activities
Individual task
Produce a class diagram for the core domain of the hospital appointment booking system. Your diagram should have 5–8 classes and must include:
- Key attributes for each class (3–5 attributes; use types)
- Key operations (2–3 per class)
- At least one inheritance relationship (with justification — apply the is-a test)
- At least one composition or aggregation (with justification)
- Multiplicities on all associations
Review the class for cohesion: can you write a one-sentence description of each class's single responsibility? If not, it may need splitting.
Pair task
Review your partner's class diagram:
- Are there any god class candidates? (Many attributes, many operations, associations to most other classes)
- Is there any evidence of feature envy? (A class with operations that mostly use another class's data)
- Are any inheritance relationships misapplied — failing the is-a test?
- Does the class structure reflect the architectural decision documented in the Unit 5 ADR?
Provide one improvement with a specific suggestion — not "make it better" but "split class X into Y and Z, assigning responsibility A to Y."
Group task — component diagram and architecture summary
As a group, produce two artefacts:
- Component diagram for the hospital appointment booking system — showing major components (at least four), their provided and required interfaces, and the key dependencies between them. Include any external system integrations (email, NHS Spine, etc.).
- One-page architecture summary written for a non-technical audience (e.g. the hospital trust's IT steering committee). This document must explain the system's structure in plain language, without UML notation. It should address: what the system does, what its major parts are, how patient data is protected, and what happens if a component fails.
The contrast between these two artefacts illustrates the difference between audience-appropriate communication — the same system, explained differently.
Review
- Class diagram — domain entities, their attributes, operations, and relationships. Granularity: class/object. Audience: developers.
- Component diagram — major modules, their provided and required interfaces, and dependencies. Granularity: deployable component. Audience: architects, senior developers, integration teams.
- Deployment diagram — physical or virtual distribution of components across infrastructure, with communication paths. Granularity: node/server/container. Audience: architects, operations teams.
Implementation documentation describes what the code does. It is derivable from the code itself and becomes stale when code changes.
Intent documentation describes why the system is structured as it is. It cannot be derived from code. It captures design rationale, alternatives considered, and constraints accepted — information that lives only in the minds of the engineers who made the decisions, unless deliberately recorded. ADRs are the primary vehicle for intent documentation.
Proceed to Unit 7: Implementation & DevOps when ready.