In one of my previous articles, What Actually Goes in a Functional Specification?, I mentioned that there are many different ways to present a functional specification, including a whole host of alternatives to the “traditional” text-and-diagrams document. One approach I have used successfully in the past consists solely of a spreadsheet and an HTML prototype. In this article I’m going to describe another approach I’ve been using recently – in which the specification is entirely graphical. The format has been well-received by business stakeholders and developers alike, so it seems like it’s worth sharing.
This article has two parts. In this first part I’m going to talk about general principles, and in the second part I’ll get into specifics.
I went through the whole UML modelling thing in the nineties and noughties (2000s). I spent hours making sure my use case diagrams had the right sort of arrows on them – pointing in the right direction, that my class diagrams correctly showed aggregation versus association, and trying to draw sequence diagrams that fitted across a single page of A4! UML was the silver bullet that was going to get business stakeholders and tecchies talking the same language. I don’t know about your stakeholders, but whenever I’ve shown any UML models to mine, I’ve had some pretty blank stares. Mind you, some of my stakeholders give me some pretty blank stares a lot of the time anyway.
I often see UML models in technical documents too. Usually, such documents are based on a standard corporate template, with section headings like ‘Use Case Model’, ‘Class Diagram’, ‘Sequence Diagram’ and so on. The author/designer has diligently produced the diagrams to complete the relevant sections. But very rarely do they add much, if any, value.
I’m not a big fan of formal modelling. And whilst we’re at it, I don’t even like the word ‘model’! It’s not a very business-friendly word, is it? If I say to a typical business person, “let me show you a model of the system”, I usually get another one of those blank stares.
I am, however, a big fan of informal diagrams. If you get a group of people around a whiteboard to discuss a concept, you will typically end up with a diagram of some sort, consisting of a variety of different symbols to no particular standard. There will be stick men to represent people. Systems get drawn as labelled boxes. Screens or pages within applications are sketched out with data fields and labels shown. Documents are often done as rectangles with folded-over corners. Notes are scribbled in at all angles. And finally there are always lines. Lines joining people to systems, systems to other systems, systems to documents, and so on. The lines often have arrows, and the direction of the arrow usually tells you something – perhaps the direction of data flow, or the action of a user on a system. The shape of the arrow head never has any specific meaning. Here’s an example of an anything-goes diagram.
Now that’s the sort of graphic my stakeholders can relate to – one that explains itself, with no need to understand any particular notation. And the word diagram is so much less intimidating than model!
The above diagram was drawn freehand using a painting tool (Paint.NET), along with a stylus & tablet. And if your team is co-located, then perhaps all you need is a whiteboard, some pens and a rubber, and maybe a camera. But in many cases you’re going to want to use a tool that draws neatly, allows you to make changes easily, and lets you store and send your output electronically. As mentioned above, I’m not a big fan of UML and, likewise, I’m not too keen on formal CASE or modelling tools that insist on pinning me down to a specific format. I want ultimate flexibility, but at the same time, I want pre-defined shapes to include in my diagrams. The obvious choice is a drawing tool such as Microsoft Visio. Here are a few features of Visio that make it useful for authoring specifications:
- Multiple tabs allow you to create a “document” with multiple “pages”.
- Pre-defined shapes – more templates than you will ever need.
- Dynamic connectors that re-position themselves when you move stuff about.
- Ability to embed other documents/objects within (e.g. MS Excel) – either directly or as file icons.
- Visio 2007 includes the capability to export to PDF format, which vastly reduces the file size (especially useful if you include any screenshots).
- Although I don’t like UML, I do like some of the individual shapes, such as actors and notes, so I’ve downloaded a handy UML template for Visio.
- I’ve created my own Visio template which gives my diagrams a user-friendly hand-drawn style.
Details in Diagrams
In the past I had always thought that diagrams were good for giving an overview of system behaviour, but that the only way to get into the detail was to use the written word. Typically, I would include a diagram in my document followed by several paragraphs (or pages) of text to describe the diagram and fill in the blanks.
In an entirely graphical specification, the details go into the diagrams. Generally this means adding notes or annotations around the edge of the diagram, with lines linking the notes to the relevant part of the diagram. The trick is to do it in such a way as to avoid cluttering up the diagram too much. The way I do this is to make the notes fainter than the main diagram, so that the diagram stands out and the notes fade into the background until you really want to focus on them. You will see examples of this technique as I talk about the various types of diagram.
In Part 2…
Oh dear. I’m already over the word limit and I know how poor your attention span is. But that should be enough to get us started.
In Part 2 of this article, I’ll talk about the specific diagrams I draw in a graphical functional specification, and how I put them all together into a single, coherent document.