Agile Documentation


Building Living Documentation Along with Code
When coding starts, we write a happy-path executable test. We use FitNesse for testing at the API level behind the GUI, but there are many tools that let you do this. (Focus on creating tests as documentation, not the tool.) FitNesse allows us to include narrative along with the test cases. This first test gives the programmer a good picture of how the code needs to work. Once the programmer has checked in fixtures to automate the tests, and the happy-path test passes, we add more test cases—boundary conditions, negative tests, edge cases, and whatever we think is necessary to prove the functionality works as desired. Testing and coding are done concurrently, more tests driving more coding, until the customers are happy with the user story. The tests illustrate how the code operates in different scenarios.

By the end of coding and testing, we have wiki pages with examples, requirements, and test cases, along with “living documentation” in the form of automated tests. These tests are added to our regression suites, which run many times per day in our continuous build process. If we make changes to the code or database, the test will fail, so we have to modify them and keep them up to date.

Maintaining Documentation
We regularly invest time refactoring our automated tests to keep them easy to maintain and quick enough for timely feedback. Are you thinking, “There’s no chance we’ll be allowed to take time for something like that”? Gojko Adzic suggests asking the business for time to update the documentation. Businesses understand the value of documentation, and well-designed automated tests are the best form of documentation.

We also refactor our wiki so we can always find the information we need. It's easy for a wiki to get out of control. We cross-reference it several ways: table of contents by business area; a page for each sprint listing all the user stories worked on, linking to the wiki pages for each story; and a wiki hierarchy by functional area. It’s a good idea to have a technical writer help you organize your wiki. It’s such a valuable knowledge base, you need the right skills to optimize it.

The Rewards
Occasionally, someone from the customer support or operations side of our business comes over to ask me about something that happened in production. For example, she might show me a loan payment that was processed and say she thinks the amount of interest applied is incorrect. I can plug the same inputs into one of our automated tests, run it, and show her the results. We know exactly how the production code works, without having a lot of debate about it. Now, perhaps she would like to change the functionality, but at least we’re sure about how the system behaves.

Reflect, Experiment, and Adapt
How do you know how much documentation is enough? Every retrospective, take a look at your documentation and decide if it’s too much, too little, or just right. Does the documentation take the form that works best for your team? Experiment with different tools and approaches. In my experience, documentation is something that has to evolve over time. You have to balance the needs of customers, developers, teams doing production support, and whoever may need to know how a particular feature or piece of functionality works, how it was tested, and what automated tests support it.

User Comments

1 comment
Seb Rose's picture
Seb Rose

To a large extent I agree with Keith (I also worked at Rational on the DOORS product), but... there is a big difference between executable documentation (such as FitNesse or Cucumber tests) and static documentation.

With the former, when the product deviates from the documentation (i.e. tests) the deviation is reported immediately through a failed test. The latter requires manual updating.

Some tools, such as DOORS, live somewhere in between. They have some ability to link from specification through to test results, using integrations with other tools. It feels (subjectively) like this is not as good as fully executable specifications - I'm not aware of any CI server with a DOORS plugin, for example - but a similar effect might be achieved.

June 23, 2011 - 5:54am

About the author

AgileConnection is a TechWell community.

Through conferences, training, consulting, and online resources, TechWell helps you develop and deliver great software every day.