If you have read any of my previous articles, you will know that I like to experiment. And in particular, I have a bit of a thing about functional specifications and looking at alternative ways of presenting them. As well as the traditional ‘words and pictures’ document approach, I’ve tried a format that consists of a spreadsheet and an HTML prototype and, more recently, a graphical format.
In this article I’d like to explore another approach. This time I’m going out on a limb – it’s not something I have actually tried and tested, so it’s more of a suggestion than a recommendation, and I’d be interested to hear what you all think about it.
It all started a few months ago when my house was burgled and I decided to invest in a home alarm system. The product I bought is a DIY installation system. It includes a central control panel, an external siren, a variety of door and room sensors, and a remote control which attaches to your key ring, so the whole too-drunk-to-remember-the-access-code-oops-there-goes-the-alarm-and-now-the-kids-are-awake scenario is a thing of the past. And it’s all wireless, so fitting it is relatively easy too.
Sounds good on paper. Assuming, of course, that the paperwork is any good. I’m sure you’ve all had the experience of buying a consumer product with a user guide that seems like it’s been written by a masochist, in Japanese, then translated into Chinese, then Swahili and finally into your own native language. Mercifully, the user guide for my alarm system is not like this. In fact, it is the opposite – it is exemplary! It starts with an introduction and overview which gives a summary of key features (different modes, entry/exit delays, zones, event log etc.). It explains how to plan out your system and where to put the various sensors. It explains the different components, how to position them, and how to set them up to connect wirelessly to one another. It is liberally scattered with useful diagrams and illustrations.
So far so good. But the most interesting bit for me is the section on how to use the control panel to configure and operate the system. The system is very flexible and has a lot of setup options. You can set the alarm duration. You can set the alarm delay. You can set up multiple zones, each with different alarm rules. You can set up multiple users, each with their own access code and permissions. You can set up four different phone numbers for the system to dial in turn to tell you that your house is being burgled. The list goes on. And all of these parameters have to be set via a 20 button keypad and a two-line LCD display panel.
And yet despite all this complexity, the instructions couldn’t be simpler to follow. First of all there is a general section explaining some core principles, like how to navigate through the hierarchical menu system. Then each function is covered in turn, with a sequence of easy-to-follow steps explaining what to do. Let me give you an (abridged) excerpt:
This menu allows the 4 digit User Access Codes to be configured for each user. The general users (1-6) may also record a 4 second message to be used with the Latch Key feature.
User Access Code
- Scroll through the top level programming menu until ‘1. USER SETUP’ is displayed and press ENTER.
- Scroll through the next menu until the required User ‘USER _ SETUP’ is displayed and press ENTER.
- Scroll through the next menu until ‘:1 Access Code’ (and the current setting) is displayed.
- To change the setting press ENTER.
- Enter the new 4 digit Access Code and then:
- Press ENTER to save and exit, or
- Press ESC to exit without saving.
With these instructions in hand, I was able to set up the system really quite easily, and I remember thinking to myself – this is great! How come all user guides can’t be like this? But then, what would all the masochists do?
Thinking in Reverse
It occurred to me that the instructions in the user guide actually look a lot like (written) Use Cases. They consist of numbered steps which explain how the user interacts with the system. Granted, they are pretty low-level use cases, and they do include explicit details of the user interface. But nevertheless, they are very use-casey. In fact, the whole user guide looks quite a bit like a functional specification, but written with the end user as the target audience.
Normally, of course, a user guide is written after the system has been designed, developed and tested. But what if the user guide were to be written first? What if the user guide was treated as the definitive specification for the system? Written by the analyst, and agreed by the stakeholders?
At first, that approach might sound a bit back-to-front. But here are a few reasons why it might be a good idea:
- A (good) user guide is very specific about what the system does, and how it is operated. If you’re focussed on explaining to a user how to use the system, you are likely to explain the system to a good level of detail.
- A user guide has to be written in user-friendly terminology – you are forced to write a document that can easily be understood by your stakeholders.
- Because it needs to include specific details of the system’s physical characteristics, it encourages collaboration with developers and UXers.
- You get two documents for the price of one – a user guide and a functional specification!
This approach would require a slight mindset shift for the analyst. He would have to be much more concrete in imagining what the finished system would look, and behave like. There would be no way of shirking on the detail – no hiding by that age-old excuse, “I’m only doing the requirements, you’re asking about the design” (and in any case, it’s all design). And as mentioned above, he would need to work very collaboratively with the development team, and with any UX specialists.
During the lifetime of the project, the user guide is likely to be very much a living document – details will change as the system is developed and constraints are hit. So change control would need to be lightweight and well-managed. An iterative or incremental delivery approach would be ideal.
Parallels to Test-Driven Development
Within the software development community, and particularly within agile circles, it has become common to practice Test Driven Development (TDD). In TDD, developers write automated tests to prove that their code does what it’s supposed to do. Importantly, the test suite for each code module is written first – before the code module itself is even started. Then, the code is written and the test suite is run. The code is only deemed complete once every test passes. In this way, the test suite defines the specification for the code module.
TDD was originally conceived as a code quality practice but has subsequently extended into the world of functional testing with extensions such as Acceptance Test Driven Development (ATDD) and Behaviour Driven Development (BDD). In both ATDD and BDD, functional acceptance tests are written first (generally automated, using a testing tool such as Selenium), and then code is written which satisfies the tests.
Clearly, there are parallels between the user-guide-as-specification idea and TDD.
Which gives me the perfect opportunity to jump on the acronym bandwagon and coin a phrase for my revolutionary new technique. Yes, you guessed it: User Guide Driven Design, or UGDD for short.
Note that my second ‘D’ stands for Design, not Development – this is an approach that drives the (functional) design of a system. It makes no comment on the development style. Perhaps UGDD could be used in tandem with TDD. But, if I’m honest I really haven’t thought it through to that level of detail yet!
I wasn’t best pleased when my house was burgled. But maybe some good will come of it. As I mentioned above, I haven’t actually tried this approach yet, so I can’t really vouch for its usefulness.
But I’m keen to hear your opinions. Do you think it would work? Have any of you tried it? Is it already a well-known technique that I’m unaware of? Or would we all be better off if the burglars had taken my PC and Internet connection?