Organic Documentation

I have always enjoyed modelling requirements in use case form. It was method for me to think a problem through and confirm understanding. The issue that I have with use case modelling is that once the solution is developed, the use case model quickly becomes outdated. Except of course if you are extremely disciplined.

From a longevity point of view, I believe there are principally two types of documentation. Firstly there is documentation that will rarely change. This would be the documentation that describes the architecture of the application, the various interaction points and the components involved in the application. Secondly there is documentation that is more volatile, and would change more regularly as features are added to and removed from the system. For example the use case model.

Ultimately one wants documentation to be organic and should be changing at the same rate as the code. With this in mind, the code is definitely a source of documentation, but this is not enough. The code only defines the how, not the what or the why. If you are following clean coding principles, then by making your code readable, without any unnecessary comments or javadocs, some of the why is conveyed in the code. But not enough of the why is covered, in my opinion.

So what can we add to the code, to add the additional meaning, that changes at the same frequency as the code? Well, the tests of course. All good software developers should be following a Test Driven Development(TDD) approach. In my opinion the unit tests if written appropriately could be used to convey the appropriate functional application knowledge. However unit tests are still technical and this is forcing something into a space that it should not really be playing in.

Behaviour Driven Development(BDD) is a progression on the TDD approach to software development. BDD bridges a gap between Scrums User Stories and the Test Driven Approach 1. It draws on the Ubiquitous Language as described by Eric Evans in his book, Domain Driven Design, Tackling Complexity in the Heart of Software, allowing business users to relate their requirements to the development team, who in turn, transform these requirements into tests and ultimately working software.

According to Dan North2 BDD is just like TDD. The difference being that it is for everyone, not only developers. If you are in a small team of only developers then TDD is fine and having a ubiquitous language to communicate with the business is not as beneficial. However when you have Product Owners, Business Analysts, Testers, Project Managers and Developers all communicating around a single domain, BDD starts to add value.

So if you have BA’s and product owners elaborating on User Stories in the Given, When, Then format. The developers can implement the tests and then complete the functionality. When you come to amending the feature, you can pull out the tests from your version control and whoever is defining the amendment to the feature can utilise the  existing tests to further define or refine the requirements.

I believe you now have the potential for documentation that truly lives with the application. In the process you are eliminating waste and adding value, where it matters most, to your client. So next thing on my list of things to write about is to create a concrete example using BDD.


  1. Behaviour Driven Development – available at
  2. BDD is like TDD if … – available at

About craigew

I am a technologist at heart and enjoy working with like minded people who show a passion for what they do. Craftsmanship is important to me and each day I am honing my skills as a software developer on a journey to one day becoming a master software craftsman.
This entry was posted in Software development and tagged , , , , , , , , , , , , . Bookmark the permalink.

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