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.
UML and Formal Modelling
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.
Love this article Tony.
Indeed, the non-traditional, or actually, the more traditional approach of just drawing a picture (isn’t that as old as Cave drawings?) is the more powerful approach for reaching business stakeholders. We can gather them around the proverbial cave fire (office) quite easily this way. And everyone can take the write board pen (chalk) and put their touches on the diagram (cave wall).
It’s quite simply tapping into what our brains have been wired to do for eons. One of my favorite authors in this regard is Dan Roam (“Back of the Napkin”), and his approach formalizes just a bit of what you’re describing though it makes very limited use of standard icons, arrows or what have you. But he lays out a schema of sorts for the primary types of cave drawings there are. Very neat stuff.
Thanks for posting this, and I look forward to Part 2!
Great article Tony! I am totally with you on formal models – I only go to them as a BA when I’ve got a tough problem to solve and the notation helps improve my thinking and thereby solve it.
This is why in my recent Business Process Analysis class I teach a very, very small subset of BPMN and focus on the process for creating meaningful models that help you learn something about the process or the business. That’s been the most rewarding work done in my career, though I do have a few formal domain models I’ve done in UML of which I’m quite proud too….
Nice article. Thanks for sharing. I must admit that even where I work, they do not have UML in place. Mock-ups or actual screen shots are used instead. I find it simple and straight forward and easy to adopt. Before I read this article, I was always under the impression that probably I am missing something by not UML and other methods that I often hear in the market. After I read your article, I feel good. Thanks again.
When I first started working on the graphical-style functional specs, they were also UI-centred – the mock-up/screenshot was at the centre of the page and it was annotated with details about specific fields and “business rules”. We found that the approach worked fine in many cases, especially when the screen was purely about data entry or data viewing. But as soon as the system behaviour became more interesting (e.g. system sends an email, system communicates with other system) then the UI-centred approach was less useful – then a process-centred approach is better – where the process flow is the main part of the page and the mock-ups are secondary to the process flow.
As with (written) use cases, I find that process flows force me to think logically through the steps the user needs to take to complete their given task – and also what can go wrong. In my experience, it tends to result in a more coherent end-to-end design.
I can relate to this article and I must admit that I dont feel “lost” anymore. To me it is more important to write a document so that stakeholders from both sides (i.e. business and IT) will understand what we are want to do. I have tried to document my BRD’s and FRS’s with a formal modelling technique, but I always end up confusing myself and spending too much time on trying to figure out the modelling language. I use formal and informal diagrams with text in such a way that the document flows and the reader will understand what we are trying to do. Must say that it works a lot better that only UML diagrams.
Thanks for the article, at least I know I am not the only one that try different avenues that work for me.
Pingback: A Graphical Functional Specification by Tony Heap | Systems For Humans
Pingback: Comparing Software Design with Building Design | its-all-design.com
Totally agree with informal diagrams for informal situations. There is plenty of choice, rich pictures from SSM, storyboards from the service design people, free form whiteboard sketches. I like storyboards where the non-user actors such as other systems can also appear as characters.
Pingback: BA Sketchbook Stencil for Visio - its-all-design.com
I’m creating some project management templates and, in doing my research, I came across this site, and it is fantastic! Thanks so much for taking the time to carefully articulate what you’ve learned and your ideas!
Nice article. Another one of the ‘less is more’ brigade
I’ve written similar thoughts on my Blog / LinkedIn:
Visio is all well and good, but it’s not cheap and it’s not always on every machine in a given BA team so, if I find a reasonable drawing tool that works for iPad / Tablet & PC / Browser and facilitates real-time simultaneous collaboration, that will be the perfect tool for me
This is good to understand. great job and thank you.