In Part 1 of this article, I discussed some of the general principles I apply when creating a graphical functional specification. I talked about my dislike for UML models and formal modelling tools. I talked about my love of informal, anything-goes diagrams. And I espoused the benefits of simple drawing tools like Microsoft Visio and OpenOffice Draw.
In Part 2, I’m going to walk you through the specific diagrams I include in my graphical functional specifications and explain how going graphical has changed my life. OK, that might be a bit strong, but I do think it’s helped.
A context diagram is always a good idea in a functional specification. It shows the system under design and how it relates to its users and other systems around it. It makes explicit the system boundaries. It gives, well, context! My context diagrams generally consist of:
- Rectangles for systems (including external systems)
- Stick men for users
- Lines showing interactions
- UML-style notes for annotations
Here’s an example context diagram:
Graphical Use Cases
Clearly, the most important part of a functional specification is a description of the system’s functions. In the past, I have produced use cases – in their written form – to specify detailed system functionality (taking my guidance from Cockburn’s Writing Effective Use Cases). I’ve spent many years trying to master the use case form, and whichever way I cut them, I’ve always struggled in two key areas:
- Getting the level of detail right. If I put all the detail within the use case, then it becomes difficult to read and digest. If I put the detail elsewhere (e.g. in a sub use case or in a section called “business rules”), then my audience has to play hunt-the-detail in my document.
- Alternative flows. Best practice is to put these separately, after the main flow, which leaves the main flow uncluttered and easy to follow, but again this results in the reader skipping backwards and forwards to get the full picture.
Faced with these problems, I have developed a new and exciting technique for presenting use cases in a graphical format. I’ve called it… a flowchart!
Flowcharts are the perfect graphical format for use cases. Each use case step becomes a rectangular process step, and each alternative flow branches off the main flow from a diamond-shaped decision box. To make things even simpler, you can even do away with the diamonds and just show multiple exit points from a process step, labeled with the relevant conditions.
I’ve tried to maintain the use case language in my flowcharts – so each step is numbered and has the general form “The user does something” or “The system does something”, so it’s always clear who is performing each step. You can do all sorts of clever things with swimlanes and colour-coding, but I like to keep them simple enough so that anyone can read them without any training. I also try to organise the flowchart so that the main flow steps are in a single vertical line, top to bottom, with the alternative flows branching off to the side. That way, the main flow stands out.
Now, what about those pesky details that either spoil the flow of a written use case or else end up hidden away elsewhere in a written document? Well, I add those in as annotations to the side of the flowchart, connected to the relevant process step. Some of my annotations are explanatory notes, but most of them are (numbered) acceptance criteria for the use case. I use a mid-grey colour so as not to detract from the main flowchart. It’s similar to the way architects annotate building drawings.
And finally, there’s one more thing I include alongside the flowchart. I include the relevant screen mock-ups. In some cases, these are just indicative wireframes, but other times they can be pixel-perfect designs. Judging from comments I’ve had on previous articles, some people don’t believe in including UI designs alongside use cases. I’m not one of those people! For me, the two sit happily side-by-side, and if I can link the two together visually, then all the better.
OK, enough talking already – let’s get graphical. Here’s a simple example of a Log On use case drawn as a flowchart. You can also view a full size version.
The first thing you will notice is that the diagram is large. A standard A4 page isn’t big enough to fit a typical use case, including annotations and screen shots, so I have been using A3 (in landscape). And my rule of thumb is that if I can’t fit a use case onto a single A3 page, Ineed to split it up into sub-use cases.
Also notice the general layout. The flowchart is on the left, the annotations (acceptance criteria) in the middle and the screenshots on the right. Connectors join the use case steps to the relevant annotations and also to the relevant parts of the screenshots. The flowchart has thick bold lines and black text so that it stands out. The annotations are more subtle, so as not to detract from the flowchart. And all the connectors have rounded corners. I just find them much more visually pleasing than hard-cornered connectors!
Functions and data are two sides of the same coin. With few exceptions, functions exist to act on data, and data exists to be acted on by functions.
That said, I have to admit that I haven’t included many data diagrams in my graphical functional specifications so far – mainly because I have been specifying enhancements to pre-existing systems with pre-existing databases. However, there are two obvious types of diagram you might want to produce:
- Entity-relationship diagrams (I usually do these as UML class diagrams, despite my dislike for UML!).
- State diagrams – to show the life cycle of entities where important or interesting.
Putting It All Together
OK, so the question now is how do I put all these diagrams together into a coherent specification?
I tend to create one Visio document per “feature”. I define a feature as a coherent set of use cases which together provide some useful function to the user. Sometimes there is a single use case. Sometimes there can be as many as ten or fifteen.
My Visio document contains the following pages (tabs):
- A cover sheet showing the version history and stakeholders/reviewers
- A context page including:
- A panel with a (brief) written summary of the feature
- A context diagram
- A list of the use cases (effectively a summary of the scope)
- A separate page for each use case
- Any relevant data diagrams
I also have a background page which provides a standard header for all other pages (and auto-populates the filename, page name and page number on every page).
And that’s pretty much it. Anything else I might need to add (e.g. NFRs) goes in on an as-needed basis, not as a matter of course.
There is one very important difference between a graphical FS and a traditional text-and-diagrams FS.
A traditional FS is written in such a way that it can be read off-line, unaided. It includes all the necessary fluff and waffle to make that possible (introduction, document purpose, intended audience, glossary etc.)
A graphical FS is not. It is short and to the point. It has content, but it does not have fluff and waffle. It has notes, but no structured, wordsmithed paragraphs. It does not lend itself well to an off-line, unaided review process. It does lend itself well to a highly engaged, collaborative design process. It is just perfect for sitting together with stakeholders to discuss, challenge and scribble on. The visual aspect of it brings the design very much to life.
For me, this has two key benefits:
- It encourages (or even forces) engagement and collaboration
- It is much quicker to write
A Means to an End
I’ve also experienced a subtle mindset shift as an author. When I write a textual specification, I have a tendency to take pride in my document. With a graphical specification, I take pride in my design.
After all, a functional specification is only a means to an end – working software. It is not an end in itself.
I’m looking forward to your comments – please leave them below.