User Guide Driven Design

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.

User Guide BurglarWhere It All Started

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 Setup Menu Navigation

User Access Code

    1. Scroll through the top level programming menu until ‘1. USER SETUP’ is displayed and press ENTER.
    2. Scroll through the next menu until the required User ‘USER _ SETUP’ is displayed and press ENTER.
    3. Scroll through the next menu until ‘:1 Access Code’ (and the current setting) is displayed.
    4. To change the setting press ENTER.
    5. 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!

Silver Lining

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

5 thoughts on “User Guide Driven Design

  1. Nick de Voil

    Great piece, Tony. Yes, writing the user guide – or at least a first draft of it – before developing software is certainly an established technique. In “The Mythical Man Month”, Fred Brooks talks about the manual as “the external specification of the product”. Tom DeMarco and Steve McConnell have also recommended this approach.

    It’s definitely a good idea to get user documentation started as early as possible in a project, preferably before any coding gets done, and to do this in collaboration with end users. The main problem with doing it in too much detail is that you waste a certain amount of effort in reworking the documentation as things change. I find that annotated UI mockups are a better focal point – you can keep software development and user documentation in sync by using them as a basis for both.

    Importantly, the UI mockups should be based on user scenarios and subjected to user testing. Otherwise you can end up with software and documentation that are perfectly mutually consistent, but which reflect the software designer’s thought processes, rather than those of the user. It’s incredible how many user guides for consumer products are still structured in terms of the interface itself rather than the things the user wants to do.

  2. Lotta

    Perhaps this is news to the BA community, but please forgive an old and cynical tech writer: in the tech comm community this has been discussed for years. That’s the whole point with well-written use cases, user stories, functional specs, and so on. I’m guessing the tech writer who wrote that alarm user guide worked together with a pretty good analyst 😉

  3. Tony Heap

    Thanks for your comments guys. Clearly I am on the right lines if Brooks, DeMarco and McConnell have said similar things! :) I should probably go back and read The Mythical Man Month – it was on my university reading list but back then I don’t think I fully appreciated Brooks’ wise words.

    But what about the concept of the User Guide *is* the specification (not merely derived from it)? I hear what Nick is saying about wasting time keeping it up to date, but if it was the one and only description of what the system does (or will do), used by the dev team and test team alike, then we would avoid the extra effort of writing both a Functional Specification and a User Guide.

    And if I had a tech writer sitting next to me (such as Lotta) I wouldn’t be too bothered about the wasted time because she’d be doing it all for me :)

    And of course the User Guide would evolve as the project progresses (with careful version control) – for example, initially it would have UI mockups, but these could be replaced by actual screenshots once the screens have been developed.

  4. SJ

    That’s a very interesting point of view. In my practice we often use the created use cases as the basis for user guides but at the same time, I would not agree that creating a user guide could replace a spec since the user guide audience is a user who mostly cares about happy path scenarios, who does not care about details but more about a result.
    If user wants to create a record, s/he wants to read in the guide how to do that, what fields to fill in and what buttons to click and I am not sure that all the details about validations performed over Save would bring any benefit to him. The guide usually does not have this info and for good reason otherwise the user guide would be twice-thrice as big and potentially useless.

  5. SLK

    It is nice to see that different sides (architect, BA and a tech writer) are engaged in the discussion. i was in all these roles and my opinion is that use cases pave a way to a user guide (end-to-end process of using a solution), to a technical specification (what data to capture, what validation rules to apply etc), and to the user experience design (user interface). Attempts to keep these parts separately (as it often is) lead to a poor solutions, poor user documentation and not re-usable tech. spec.
    The business user wants to know: which form to use within a daily activity, what fields to fill in, where to select data from a drop-down list and where to add something new to these lists as business changes. The good user guide gives a high level overview of how different users are connected through a solution to mitigate a risk of resistance to change during implementation.
    The described approach I use in all my projects. It does not take too much time to keep everything in synch, it mostly about right collaboration within the project team.


Leave a Reply

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