We have found that communicating our system designs with clients is most usefully done with diagrams rather than large chunks of text.  Some years ago, we looked at using UML Use Case Diagrams for this communication – but see what Martin Fowler has to say about them in  ‘UML Distilled’:

“But almost all the value of use cases lies in the content, [of the textual cases]  and the diagram is of limited value.’

In other words, in his opinion, you should use the textual Use Cases, not the diagrams (which just map those texts visually).

‘Pure’ UML also seems to disappoint in terms of producing very dry monochrome diagrams with stick figures, and simple primitives such as boxes and ovals.  Is this really the best we can do to convey the use of a system?

In a world where design and documentation steps are often incomplete (or never undertaken), the most important feature of any documentation you do have the chance to do is to set the scene for all parties. We have found these diagrams useful to:

• Design the system itself: creating the diagram is often a prompt to discover new requirements or steps that are necessary in the process;
• Describe the feature to management, both of the client and development;
• As a basis for estimating the work required;
• As a means of introducing individual developers to the work they need to undertake.

Here’s an example; an outline of a proposed enhancement to a Human Resources (HR) system that was intended to add the ability to offer overtime to employees and have the employees volunteer to work for a given offer.

For this particular client, the original request will have come in the form “We want a system to track staff overtime”, and after initial discussions with the stakeholders (most especially managers in the call centre that often requested staff to come in for additional work) the requirements will have been padded-out.  For example, we discussed the need for overtime offers to be authorised, and decided quite early on that we would prefer to limit who could create the overtime offers, rather than have a larger number of people eligible to create them, but then insist each offer be authorised by senior management.

To read the following diagram; the black rectangles are screens on the application, and / or views onto the information. In this case, the pre-existing application was an internal website.  For example, a Manager might start viewing the screen to List Overtime Offers.  On that screen, they have a function to Add a new offer, show the detail of existing offers, and so on.  The black arrows suggest traversal to a different screen, but remember, this is mostly intended to show that the user will now be presented with different data, and how you present that may vary based on the technologies you use and the user interaction standards you have in place.

Meanwhile, the Team Member starts their experience with this system with the ‘Overtime Alert’ view that might be presented on the pre-existing System Home Page (e.g. what they saw when they logged-in). This would give them the option to Show details of the overtime offer, and potentially then to Accept the offer.  Finally, an employee would see their subscribed overtime hours on their work calendar control (again, a pre-existing part of the system).

The blue lines on the diagram connecting to the yellow boxes represent accesses of the stored data.  Not every access is recorded, but we ‘should’ record the most important data retrievals or stores*: this is so we can look at an entity and see that data is recorded (arrows to the entity) and used (arrows from the entity)… there may be situations where you consider this acceptable (e.g. if you want to imply storing log data, but not show any log-analysis tools you use) – but it can often lead to discovery that you need additional functions.

It should be clear that while this is not an all-encompassing diagram, it does cover a lot more than a list of use-cases!  It attempts to convey the screens or views an actor might need to transition through; it implies the steps in the process (and we have certainly drawn these diagrams with large 1, 2, 3… numbering to draw attention to the order of the overall process.  Some of the details in the diagram, such as the data model or Entity Relationship part, presume the reader is aware of the pre-existing database tables – but this is ok. This is not a complete specification of a system.

One of the things that is really useful about this is the scale of the project that is included; it really can be used to cover the macro- to micro-scopic; even if some information may have to be inferred.  For example; let’s examine the Team Member user-experience when they ‘View Overtime Offers’: We might want them to see a list of available overtime slots – Accept ones that they are eligible for (e.g. not already working during that timeslot). If the user accepts an offer, what happens? The implication of this diagram is that the Overtime entity will be updated (probably the Subscribed Hours field, but I’d suggest that this design element would not go make it to production code 🙂 – Managers might like to see ‘Subscribed Hours’ but we might calculate it rather than store and maintain it) and inserting an EmployeeOvertime record that will store that employee’s interest in the overtime slot.  However, we might also note that Managers can Reject an employee’s acceptance of an offer; so we may need to update the design to allow for some kind of Employee Overtime Status lookup that we could then show to the team members when they View the offers!  Do we have to search through pages of documentation to find the data model; no it is on this page!  There are other possible solutions to that issue of course.

Is it Wise to include the Entities?

For this particular customer; yes. They were very used to having full access to the database, and they were very interested in data storage and how they might report on it later.  This probably will not be necessary or appropriate for all clients, but was very useful in this case.  If you decided against drawing the entity relationships, you might want to use some other technique to indicate the sorts of data that were stored with something like a tag-cloud perhaps?

Summary

Perhaps it is unwise or incorrect to refer to UML Use Case diagrams when introducing this diagram. We believe it is substantially more useful, and goes a long way to demonstrate the relationship between functions or processes; information that would not leap out at you from text Use Cases. Furthermore, it allows rapid re-evaluation and modification of the system design without finding ‘all the references’ that might need to be updated with other design approaches.  Should you wish to write full use cases, then this is certainly a useful springboard to do so, and you could obviously do the same for wire-frames for the views.  Tools like Visio allow you to set up interactive diagrams that allow you to move between pages of the diagram by double-clicking elements.

If nothing else, these diagrams are certainly a useful aide-memoir when discussing a design proposal and for informing all levels of the design – and it is extremely useful for estimation as a single page visually shows you Entities, Screens and Reports that need to be built or modified.  Although it’s not normally the only documentation that we would produce for a system design, such a diagram will be a key element of such documentation.

 

Notes

* This perhaps has some origin in past experience with Hierarchical Input Process Output (HIPO) diagrams that placed great importance on the data each process required, and the data it output.  They are long-gone, but storing data is still considerably important feature of many applications!