Driving Development

Recently 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 right.


First up you should note that Daniel works for the company that created the application he name drops in his post, Bumblebee. However his approach did ring a few bells with me, as it would sit nicely alongside my belief that, when working in an agile development environment, you have to eschew traditional writing processes and aim to grab and pillage information from wherever you can, trickling into what will become the final publication.

What I’ve realised is that by partly adopting the process suggested by Daniel we, the technical writing team, can be involved right up front and the documentation can be one of the methods used to validate the software as it is being built.

In an Agile team, the emphasis is on Test Driven Development where a chunk of work, derived from a customer story, first has acceptance tests written for it before any coding can start. The aim of the developer is to make sure his code meets the acceptance tests. In our organisation the test team provide guidance and input to what those tests should be, but the onus is on the developer to make sure they write the tests first.

So what if we slip the technical writer into the mix? Well first up we can roll up a level to the requirements gathering point and rather than one or two developers talking to the customer to capture their requirements in the form of customer stories (with the customer being the ‘sponsor’ of the requirement and not always directly a customer of the functionality, for example in the case of a sales or marketing driven stream of work) instead the technical writer will be there to capture the stories and flesh them out to an appropriate level.

From there it should be easier to break the stories down into tasks, and as we act as user advocates, those tasks should better reflect the end user. Once the tasks are in place we can write up the documentation to that level alongside the creation of the acceptance tests and, with both tests and a few paragraphs describing the aim of the functionality (how it helps meet part of the overarching customer story), and how the functionality is expected to work (how the end user will use the functionality), then we have a very powerful way of ensuring requirements are met.

As it happens on the guys in my team is already working in this sort of manner and it’s going well. Yes it’s a mind shift for both the technical writer and the development team but it appears to be paying dividends. If everyone agrees we’ll roll it out across the other areas of development.

And then, finally, I will be able to claim that my department is running development! Mwuhahahaaa!!

OK, maybe not.

P.S. I’m aware some of my colleagues read this, don’t worry I know who you are, and you will be treated fairly when my team assume power…


  1. I’m happy to be “almost right”, because then I’ve got more to learn… 🙂

    Do you have any pointers to more info about how you work? It would be interesting to hear.

    I talked a bit about mixing and involving competences in my blog entry
    and now I realize I should have put a technical writer there as well!

    A clarification: The relation between Bumblebee and Agical is
    that I wrote Bumblebee on my evening hours and I use the Agical website to host the site and the downloads. The application is free, Apache 2 licensed, and open source. 🙂

  2. Hi Daniel, thanks for popping by with your clarification. Good to know the motivation.

    As far as ‘how we work’ it’s largely built on the priniciples of Extreme Programming, but we have tweaked how things work a little to better suit our workplace.

    If you skip through the previous posts in the Agile category on this website, you’ll get a better feel for how we work.

Comments are closed.