User-Guide-Driven Development

In my work with Bumblebee I use an approach I call “User-Guide-Driven Development”, or UGDD for short. The mechanics of UGDD is similar to that of Test-Driven Development (TDD), but before I write the test for a feature, I write a snippet of the user guide describing the feature I am about to implement.Whereas TDD focuses on the functionality, UGDD focuses on both the functionality and the usability, and the “TDD mantra” becomes:

explain->red->green->refactor (repeat until done)

The refactoring part is of course refactoring of both the user guide and the code, since you are bound to learn things from implementing the code.

In practice, I write the documentation snippets in comments in the test cases, and then I use Bumblebee to harvest the comments and put them into a nice looking document.

The term “User Guide” is deliberately chosen; I want to put the focus on the user. One name for this that I have come across is “Documentation Driven Development” (DDD), but I believe that name takes focus from the user an redirects it to “just writing stuff about the application”, and I believe that won’t give the same benefits. And besides that, “DDD” usually refers to Domain Driven Design.

This approach has led me to improve my understanding of what the user sees of the application, and I am constantly forced to explain to my “virtual teddy bear user” how to use the application.

Small inconsistencies deep down in the code bubble up to the surface like bad-smelling bubbles. Traditional TDD would probably not even make me aware of those issues, but UGDD makes them painfully obvious when you have to explain special cases or workarounds.

When writing the documentation, you are also forced to think of who you are writing for, and for that reason it is good to create Personas. The small user guide snippets becomes a kind of narrative.

Just as with TDD, it is all about raising the hygiene factor of what you produce, and it’s no guarantee for writing perfectly usable software. It’s also not a replacement for having a usability expert on your team, since you still need to conduct e.g. usability testing of the application.

UGDD has made me and other people I know write better APIs and applications. I would be happy to hear from you if you try it out, both the good, the bad and the ugly experiences.


13 Comments (+add yours?)

  1. Peter Arrenbrecht
    Aug 25, 2008 @ 07:47:28

    Daniel, I couldn’t agree more.[1] And I take with me the hint about clearly defining the target audience (personas) – thanks.

    I do like your attempt to emphasize the user in the name, but the acronym, UGDD, doesn’t strike me as too catchy. Myself, I came up with DDT, that is, “documentation-driven testing” as a name for this approach, but I think I like the nice and short term “literate testing”[2] that the Python doctest guys use even better.

    I have written a tool that works just the opposite way from Bumblebee’s, in that it cites source code into docs written separately (see JCite[3]). But the reasoning for why one should do this is the same. A very full-blown example of its use is AFC[4] (note that the Excel sheets are cited, too).

    I have also collected a few links to other sites with takes on this approach.[5]




  2. danielbrolund
    Aug 25, 2008 @ 08:19:29

    Yep, UGDD isn’t that catchy, but I do like the explicit user focus. On the other hand, Bumblebee can be used for other literate testing as well.

    Thanks a lot for the links!


  3. Trackback:   Putting the user back in user documentation by Communications from DMN
  4. Trackback: User-Guide-Driven Development Writer River
  5. Trackback: Driving Development | one man writes
  6. Raj
    Sep 09, 2008 @ 09:32:28

    Informative article. User-driven documentation is the hour of the day, and hopefully everything in near future will be user-driven. Oh btw, I know a few companies, where the generated content is manager driven 🙂


  7. danielbrolund
    Sep 09, 2008 @ 19:50:02

    I sure hope things will be more user driven than today, and when you lack a user you can “teddy-bear” him by writing the user guide, and all of a sudden you’ve got user-guide-driven development!


  8. Trackback: Phasing over from java to scala pt. 3 - What about the tests? « The point is missed
  9. John Reynolds
    Sep 12, 2008 @ 20:25:12

    You might enjoy my similar experiences from back in the 80’s:


  10. Trackback: Improving documentation quality « writingsparks
  11. danielbrolund
    Sep 14, 2008 @ 17:33:36


    As so often, good ideas are old ideas. 🙂
    It was very interesting to read your post, and I hope UMDD/UGDD can get a revival.


  12. Trackback:   Weekly links roundup by Communications from DMN
  13. Trackback: xDD: An Overview « Den bloggande terriern

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: