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.