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.
RSS-feed
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]
Cheers,
-peter
[1]http://peomeint.blogspot.com/2006/08/beyond-tdd-documentation-driven.html
[2]http://docs.python.org/lib/doctest-soapbox.html
[3]http://arrenbrecht.ch/jcite/
[4]http://www.formulacompiler.org/doc/tutorial/basics.htm
[5]http://peomeint.blogspot.com/2006/11/documentation-driven-development-other.html
Comment by Peter Arrenbrecht — August 25, 2008 @ 07:47
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!
Comment by danielbrolund — August 25, 2008 @ 08:19
[...] align=”left” />While going through some Google Alerts the other day, I stumbled across this blog post that discusses user-guide-driven development. What the author wrote about bad software code [...]
Pingback by Putting the user back in user documentation by Communications from DMN — August 28, 2008 @ 12:56
[...] User-Guide-Driven Development [...]
Pingback by User-Guide-Driven Development Writer River — August 29, 2008 @ 12:42
[...] Daniel Brolund posted an idea around something he termed User Guide Driven Development, it’s an interesting read and, you know what, he’s almost [...]
Pingback by Driving Development | one man writes — September 2, 2008 @ 20:52
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
http://coloredwritings.blogspot.com
Comment by Raj — September 9, 2008 @ 09:32
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!
Comment by danielbrolund — September 9, 2008 @ 19:50
[...] UGDD I have come to the conclusion that I need to add some features to the SiteGraph. I need to [...]
Pingback by Phasing over from java to scala pt. 3 - What about the tests? « The point is missed — September 10, 2008 @ 22:46
You might enjoy my similar experiences from back in the 80’s: http://thoughtfulprogrammer.blogspot.com/2008/09/user-manual-driven-development.html
Comment by John Reynolds — September 12, 2008 @ 20:25
[...] involved in the documentation process at the initial stages of software development itself. Click here to read Daniel’s [...]
Pingback by Improving documentation quality « writingsparks — September 14, 2008 @ 08:03
John,
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.
Comment by danielbrolund — September 14, 2008 @ 17:33
[...] Every tech writer’s fantasy: user guide-driven development [...]
Pingback by Weekly links roundup by Communications from DMN — November 1, 2008 @ 12:02