Published using Google Docs
Chris Meudec's Lean and Agile UML Reference
Updated automatically every 5 minutes

Chris Meudec's Lean and Agile UML Reference

Chris Meudec

First Version March 2014 - Latest Version December 2020


Recommended Tool


Use Case Diagram

Package Diagram

System Sequence Diagrams

Domain Model Diagram

Object Diagrams

Sequence Diagrams

Design Class Diagrams

State Machine Diagrams


This is my version of a lean reference and agile usage guide of the UML; I was inspired by Allen Holub’s version of course.

I aim to provide a lean reminder of the UML needed 90 per cent of the time within an agile approach to software development and also provide basic guidelines: it is not to teach the UML nor tell you how to use it.

Feel free to provide comments directly using Google Docs commenting mechanism on the Google Doc version of this UML lean reference. And if you are reading the Google Doc version you can also access the equivalent web version of this UML Lean Reference.

I use UML notes to explain the basics of the diagrams:


The diagrams below are just examples to illustrate the notation: they are not related to each other, or in other words, they do not belong to the same system and are used for illustration only.

Why? Why do we need agile UML? Does using the UML mean abandoning Agility? Are these things not mutually exclusive? Well, I do not think so nor does this guy nor does Martin Fowler as he explains in his ‘Is Design Dead?’ (Design as in OO design or code design if you wish) keynote address at the XP 2000 conference.

If you need a more detailed summary of the notation I recommend Allen Holub’s version (it is not a complete reference) if you need just enough UML read on...

Recommended Tool

In an agile environment, I recommend UMLet (desktop) or online version because it is nearly as quick as sketching on a whiteboard. Not everybody likes it, but show me a faster alternative and I'll change my mind.


How to use the UML within an agile process? Some guidelines:

Use Case Diagram

What For: To quickly represent the functionalities of the system under consideration, its context (the actors), and the key ways it will be used (the use cases).

Dos: Do keep them simple; Do identify your actors; Do identify the keys ways actors will use your software to give you your ‘use cases’; Do link actors and use cases with simple lines without arrowheads nor labels; Do name your use cases starting with a verb so that a sentence can be constructed; Do add the boundary box (everything within it is a system, or subsystem, that you have to develop); Do use the CRUD (Create Read Update Delete) acronym for major entities.

Do Nots: Do not add arrowheads; Do not add labels on the link; Do not link use cases with one another; Do not add ‘System’ as an actor; Do not show the flow or sequencing of use cases: a use case diagram is not a flow diagram; Do not add Database as an actor.

Use Case Diagram.png

Package Diagram

What For: To give an overview of the overall code’s organisation: its architecture. A typical architecture is a layered architecture (mainly with three layers: a view layer, a domain layer and a services layer) so that some separation of concern is achieved and the code does not end up in a big mess and to allow the implementation of a distributed system.

Dos: Do choose a high-level architecture and maintain a separation of concerns between your layers; Do feel free not to create a package diagram initially: they are mostly useful for larger systems; Do add dependencies between packages (downwards only if you can in a layered architecture).

Do Nots: Do not go too deep and add too many details initially: in fact, just the layers and the main inner packages are sufficient at first.

Package Diagram.png

System Sequence Diagrams

What For: They formalise the interactions between the actors and the system within a use case. Therefore there should be one System Sequence Diagram per use case. Their main benefit is to clarify use cases and identify the events (and arguments) sent from the actors to your system.

Dos: Do create them they as they are very useful; Do change your detailed use cases if necessary to match your System Sequence Diagrams (and vice-versa of course as consistency across all artefacts is important); Do only show the System to develop as a single entity as a black box and the actors involved in the use case only; Do try to find descriptive names for your events generated by the Actors; Do add arguments to your events; Do use camelCase (for increased readability) for your event names and arguments; Do focus on the events generated by the actors and received by your system.    

Do Nots: Do not merge all the use cases in a single System Sequence Diagram: there should be one System Sequence Diagram per use case; Do not focus too much on returned information from the system; Do not focus too much on internal processes within the system; Do not add an internal database as an actor (unless it is truly an external database independent from your solution)

System Sequence Diagrams.png

Domain Model Diagram

What For: A static diagram (i.e. representing the code’s breakup in terms of classes not what happens at runtime) which shows the initial classes of the domain layer of a system (do not consider UI nor services classes), their attributes and relationships. A domain model is a simplified class diagram; It leads to a Design Class Diagram later on after the dynamic design has taken place. It is typically only created during the first iteration: later iterations add onto the Design Class Diagram as necessary;

Dos: Do create one for your first iteration and update your design class diagram after the first iteration; Do use camelCase for the attributes’ names; Do name the associations meaningfully to improve communication between team members; Do ensure that all your data members are pure data values (i.e. do not represent objects): use associations between classes to represent relationships between objects; Do add multiplicity information (is it a 1 or * type of association between objects?); Do simulate what will happen at runtime by reading the detailed use cases and updating an object diagram (see below) that respects your proposed domain model.

Do Nots: Do not include GUI classes as they belong to the view layer; Do not have a class with an s at the end, a class represents one entity, it is a template, so, for example, it’s User, not Users. Do not have spaces in your class names and ensure they start with a capital letter; Do not include methods; Do not add arrows on the associations between classes; Do not use associations to represent actions that actors can perform such as 'checks', 'login' or 'create' as associations between classes represent need to know relationships, not actions that can be performed. Do not add role names; Do not worry too much about the type of attributes; Do not worry about members’ types of visibility (e.g. public, private or protected); Do not add data members that are an object (or represent an object by using a unique id) or collection of objects: use associations between classes to represents relationships between objects;  Do not worry too much about multiplicity differences between 0..1 and 1 (nor between * and 1..*); Do not worry too much about the differences between composition vs. aggregation vs. normal associations; Do not add Database classes: they belong to the services layer;

Domain Model.png

Hotel System Domain Model

(you may have to zoom in or right-click the image and select ‘Open image in new tab’)

Object Diagrams

What For: Object diagrams can be used in an informal way to animate a domain model diagram or design class diagram. Instead of looking at classes, objects are represented and we can simulate the behaviour of the system according to various scenarios (e.g. various use cases) by showing the state of our objects to ensure that the classes proposed will be able to sustain the expected behaviour of the system. Because this is such a dynamic diagram and not at all a documentation artefact that needs to be recorded I recommend the use of a whiteboard rather than a software tool as it is much more practical.  

Dos: Do simulate the behaviour of your proposed objects according to your domain model and design class diagram and try to discover problems when acting out your user stories (or use cases); Do be consistent with your domain model or design class diagram when creating object model and update them as necessary.

Do Nots: Do not use object diagrams as documentation: learn from them and update your domain model and design class diagrams as appropriate, then discard them; Do not be fussy on how your object diagrams look, just use a whiteboard and different colour pens; Do not invent classes, attributes nor associations (i.e. elements that do not exist in your class diagram) when creating object diagrams: be consistent.

Object Diagram HotelSystem 1 Start.jpg        Object Diagram HotelSystem 2 Login.jpg

      Hotel System with some Tourists (ts) logged in                        Hotel System after ‘Jane’ logs in via a Session s3

Object Diagram HotelSystem 3 Rooms.jpg                Object Diagram HotelSystem 4 Reservation.jpg

           Hotel System with some Rooms        (rs)                              Hotel System after ‘Jane’ has reserved Room ‘A1’

Sequence Diagrams

What For: Sequence diagrams show the interactions, collaborations, between objects via method calls: they represent the dynamic aspects of a system—the algorithms. Using the classes discovered so far, the System must handle the individual system events generated by the Actors (typically from the GUI for human actors or from a network for other non-human actors) and create an algorithm involving many types of objects to fulfil the responsibilities that the system must implement. The notation is identical to the notation for System Sequence Diagrams but is used to show the interactions between individual objects (low level) rather than between the System and its actors (high level). These diagrams are, unsurprisingly, the most difficult to create.

Dos: Do create a separate Sequence Diagram for each event received by your System from its actors; Do start your Sequence Diagram by the event generated by the actor and assign the responsibility of handling it to the controller; Do try to find descriptive names for your methods; Do add arguments to your methods; Do use camelCase for your method names and arguments; Do differentiate in your notation between a simple object and a collection of objects.

Do Nots: Do not invent types of objects that do not exist according to your class or domain diagram; Do not increase the coupling of your design by allowing an object to call the method of another without a reference from an argument of the method call or from permanent visibility according to your domain model.

Sequence Diagram.png

Below is an example of the create message in Sequence Diagrams to create instances. Implicitly the create message calls the constructor and, this is typically not shown, return a reference of the newly created object that is kept locally within the caller.

Lean UML Create Sequence Diagram.png

Finally iterating over a collection of objects is quite common and is illustrated below.

Lean UML Iteration Collection Sequence Diagram.png

Design Class Diagrams

What For: A Design Class diagram shows your classes, their attributes, their methods and their relationships: it is a summary of the structure of your classes and thus your code. It uses the same notation as Domain Models but adds much more details, for example, methods are added, associations are transformed by adding visibility arrows and replacing association names with role names.

Dos: Do take your domain model as a starting point (or your existing Design Class diagram if you have one from a previous iteration); Do add the necessary method according to your Sequence Diagrams; Do add role names and visibility information as necessary from your sequence diagrams; Do maintain consistency with your other diagrams by modifying them if necessary.

Do Nots: Do not add classes never mentioned before; Do not show getters and setters in the list of methods: they are of little documentation interest; Do not show constructors unless their arguments are of interest.

Lean UML Design Class Diagram.png

The notation for the Singleton Pattern is:

State Machine Diagrams

What For: State Machine Diagrams show, for objects whose behaviour depends on their past, their history, the range of possible behaviour and the events that trigger that change of behaviour. They are a great way to explore or document object behaviour over time. They can be implemented very easily into code.


Do Nots: Do not create a state machine diagram unless you need to: most of the time they are not necessary;

State Machine Diagram.png

 Christophe Meudec 2014-2038