Photo of Jamie & Lion

The personal site of Jamie Knight, a slightly autistic web developer, speaker and mountain biker who is never seen far from his plush sidekick Lion. View the Archive

Topics: Autism Development

Documentation Driven Development in BBC Frameworks.

Every development team have their own process, there is a mix of formal processes (such as BDD) and more adhoc processes which have grown organically.

The process followed often depends on what the team is building and how the build (or product) is managed. These factors and many other effect which development workflows will work and which will not.

In the BBC Frameworks GELs team we follow a process we call Document Driven Development. I joined the team a few months ago, here are my thoughts on DDD so far.

Why DDD?

DDD as a process is pretty simple. You write the documentation first.

To many developers, this is a little crazy, for most projects the end user documentation deals with the user interface and explaining the user interface is not something the developers are required to do.

For these situations, the UI is often abstracted into user stories and acceptance criteria. Behaviour is defined to varying degrees, sometimes very clearly (cucumber and BDD) and sometimes not at all (hand wavy product owners!). For a product with a UI this makes sense.

However, in the GEL’s we mostly build APIs and shared tools. Our end users are other developers, we aim to make their lives easier.

By writing the docs first, we start the process with our end users (other developers) in mind.

At first, straw man proposals are put forward and discussed. Out of the discussion comes an agreed API and a collection of terms. Next we create the end user documentation, detailing the API, all the possible parameter values and corner cases (including errors).

Once the documentation is agreed within the team, we push it out to other teams for comment. We also use the documentation to think about what acceptance and unit tests are required.

From here on, we follow a more typical TDD approach. We work iteratively, writing tests first then implementations.

Things do change during development, so small API changes can be quickly picked up and iterated on as they happen, starting with updating the documentation.

In practice

I have personally found the approach to be very useful, writing the docs upfront keeps our end users needs in mind, but we have the flexibility to evolve our solution as we develop.

Having a document to refer to can help explain more of the context. By forcing the full length prose explanation complex and confusing options quickly become apparent. If i cannot explain what i am proposing to build in a few sentences, then thats a strong hint that something is wrong.

All in this approach is not that different to BDD, just for our end users, user stories don’t really provide the right format for feature description and ideation.

Using DDD we end up higher quality, coherent and consistent, documentation. The documentation quality reduces our support workload and allows us to focus on delivering value to other developers around the business.

Published: 28 August 2013 Permalink

Comment

  1. Jamie Rumbelow · Aug 28, 08:29 PM ·

    Thanks for sharing this Jamie; DDD has been really useful for me too when working on libraries or other code intended to be plugged in as third party.

    While test-driven code can inform better code design, unit tests rarely help with high-level interactions, and it’s surprising how regularly I find myself sitting down to build a class only to realise I haven’t thought through its responsibility. Writing the documentation first – the public API, how I should interact with it externally – is really useful for considering the ‘point’ of the code. What’s its purpose? Why am I even doing this? What problem am I solving?

    The next step up from DDD is literate programming (http://en.wikipedia.org/wiki/Literate_programming), which gives you a full prose explanation of the code, which looks really interesting too!

Your Comment