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