A Graphical Functional Specification – Part 2

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. :)

Business Analysis in PicturesContext Diagrams

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:

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:

  1. 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.
  2. 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.

An example graphical use case

An example graphical use case

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! :)

Data Diagrams

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:

  1. Entity-relationship diagrams (I usually do these as UML class diagrams, despite my dislike for UML!).
  2. State diagrams – to show the life cycle of entities where important or interesting.

What I don’t have a good answer for is how to capture the fine details for each data entity (entity descriptions, attribute types and constraints). Of course, formal modelling tools support this, but really I want something simpler. A tabular format works well, but is clumsy to produce with a drawing tool. Visio does have the capability to embed Excel documents on a page, either visually or as a file icon, so that might be a good way to do it. I’d be interested to hear of any suggestions.

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.

You can download an example graphical functional specification in both PDF format and (zipped) Visio format.

Assisted Reading

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:

  1. It encourages (or even forces) engagement and collaboration
  2. 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.

Further Reading

There’s more to business analysis than just writing Functional Specifications. I’ve tried to capture the end-to-end process I follow in the article Business Analyst Designer Method.

21 thoughts on “A Graphical Functional Specification – Part 2

  1. Jeff Harrell

    Love the last paragraph. I’ve found that I can effectively communicate concepts and specs with a larger group of users when I use a graphical method rather than just narrative. Though we’ve already envisioned our design, the user is often not aware of the process or focused only on their piece of the pie. Good post!

    Reply
  2. Craig

    Tony, thanks for sharing. Lots if good ideas here.

    On data: try call outs on the wireframes. Simple. Easy to work with, and keeps you out of the implementation design.

    Reply
  3. Ebony

    Hi Tony

    I am a Business Analyst living and working in Australia. I have stumbled across this site and your blogs and I really like the content.

    Reply
  4. swtp

    Hi,
    I’ve recently started reading your work and you’re very informative, clear and thorough. I like your articles. Keep writing since you’re doing such a good job!

    Reply
  5. Ajay

    I have been experimenting with different ways to visually represent functional specifications..and your ideas simply add a fresh perspective to it!

    Reply
  6. Srila Ramanujam

    Personally am a graphics oriented person, who understands requirements from diagrams than a long descriptive paragraph. But your ideal option of suitably combining both, where text is warranted and also to the extent it is warranted, gives the FS all its purpose and power of ‘representation’…..thanks, hopefully I’ll remember to incorporate enough graphics in my future FS’s!

    Reply
  7. Rose Poruthur

    Hi Tony,

    I find that your articles help open up my eyes to so many workable solutions and I am hyped about them. DO keep up the good work. It is really appreciated.

    Reply
  8. raghu

    Hi ,
    I’ve just graduated from college with a bachelor of engineering in Computer Science Degree, I’ve joined work as a trainee business Analyst in a start-up firm with about 35 employees……..I’m the first BA they’ve roped in to start the BA Division in their company…Kindly freshen me up with how to go about this whole thing……as BA has many flavors I’m a bit awestruck with its diversity…I’ve been told to research on my role for a couple of weeks,Please find time to reply me as I seriously need some guidance…….

    raghu

    Reply
  9. Helen Lomas

    Great articles Tony, I spent years reading various ‘methods’ for representing requirements thinking that I needed to be more formal (having been largely self taught), and kept coming back to the good old fashioned ‘high level process map’ which is a lot like your context diagram and specific process flowcharts with the ‘decision branches’ on them. Always worked better than anything else for me

    Reply
  10. Anthony Okolie

    Great exposition Tony! You answered my question towards the end of the article. At the point when you were talking about screen shots I was wondering whether you were specifying the system or designing it. What I now understand is that you were doing the later implying you have enough skills to do that. Will it be right to assume that one should leave out the screen shots if the intent is to specify the “What” and not the “How”? I am thinking that not every Analyst (especially those at the entry level) can serve as a designer as well.

    Reply
    1. Tony Heap Post author

      Hi Anthony,

      Opinions differ, but my own view is that the user interface design should always be included within the Functional Specification (I see it as part of the “what”), even if it means getting somebody else to do it so you can paste it in.

      The alternative is that somebody else is going to take your document and re-create it with the screenshots added – two docs instead of one – not so good.

      Remember, screenshots don’t have to be pixel-perfect – you could create representative wireframes using Balsamiq or similar. Another alternative would be to issue a first version of your doc without the screenshots but then get them added in at a later stage, once the UI design is complete.

      Reply
  11. Jay

    Hi Tony

    Thank you so much for sharing all your insight. It’s been 10 years since I worked as analyst/designer. Back then I used old school software development methods. I was looking desperately to find something more agile in action. Your blog has been a revelation.

    During these last years I’ve done a lot of process definition and management, and had to work with flowcharts almost everyday. Often I’ve been involved in making managers and employees unfamiliar to flowcharts understand and sometimes produce them. I’ve learned a lot out of these experiences. Sometimes I think I should write a little usability manual for flowcharts.

    This takes me to the point. Overall I like your flowchart modelling. However, I think you should visually differentiate the action boxes from the response boxes, as by nature they represent quite different concepts in the process. Probably part of your audience like testers would appreciate the differentiation. Have you thought of using a different background color (e.g. pastel pink or pale lime) on responses?

    Jay

    Reply
    1. Tony Heap Post author

      Hi Jay,

      Providing some visual distinction between user and system steps is a great idea. Colours would work well. Swimlanes is an option but might clutter up the page too much. On a recent project we distinguished human steps from system steps by putting diagonal lines across the bottom left and top right corners of the rectangles for the system steps.

      Let me know how you get on!

      Reply
  12. Dave Couture

    Great article.

    I like your last sentence “After all, a functional specification is only a means to an end – working software. It is not an end in itself.” Effectively, functional specifications are requirement specifications that ensure we have properly understand the functional requirements, they are not software design. They are a part of the process of creating software, but they are not the process.

    Concerning UML, we must keep in mind that functional specifications are for the users. They need to be able to understand if we have correctly understood their needs (functional requirements). I’m more flexible about UML for functional specifications but less for software design. I’m using use case, wireframe, etc. for functional specifications and I stick to UML with class, component and deployment diagrams for software engineering.

    Reply
  13. Motu

    Hi Tony,

    Great post. Possibly silly question – Why are the steps numbered in increments of 10 instead of 1?

    Also, how come your alternate flow for a failed log on is numbered 50 like the standard successful log on?

    Thanks,

    Motu

    Reply
    1. Tony Heap Post author

      The steps are numbered in tens so you can insert steps without having to re-number. The duplicate 50 is a mistake – it should be 50a! [Update 30/08/2014: I’ve fixed this now]

      Reply

Leave a Reply

Your email address will not be published. Required fields are marked *