Problem solve Get help with specific problems with your technologies, process and projects.

Software documentation is important in Agile environments

It’s a fallacy to think that documentation is not important in agile environments. Agile expert Lisa Crispin points out that "living" documentation that stays kept up-to-date can be attained by the use of wikis or via automation tools, using techniques in which the tests themselves provide the most current documentation.

What documentation (if any) do you recommend in agile environments?

The Agile Manifesto states that we value working software over documentation, but that doesn’t mean we don’t value documentation highly. Naturally we need to document the work that we do and how the software works. A corporate knowledge base is essential. We especially need to learn from our mistakes so we don’t repeat them.

When I worked in traditional phased-and-gated software projects, we often spent weeks writing requirements documents and test plans. These started getting out of date as soon as coding began, and they were rarely updated with the actual functionality that was delivered. With agile development, we strive for “living” documentation that evolves along with the software, always accurately reflecting current system behavior while maintaining a history of past behavior.

Automated regression tests form some of the most important documentation, because they must always be kept up to date or they will fail. I like tools such as FitNesse that let you incorporate narrative documentation inline with the automated test cases. A given/when/then format is easy for everyone, including business experts, to understand. Many tools support this behavior-driven style format, including FitNesse, Robot Framework, Cucumber and Twist just to name a few. Through our continuous integration and build process we can access a history of past test results as well as getting instant feedback on the very latest code changes.

As I described in Using a wiki to manage Agile ALM, my teams have found a wiki to be a great place for the whole development team plus the business experts to collaborate on creating and maintaining accurate and complete documentation about the system. Combining a wiki with corresponding automated regression tests enables us to easily research any questions about what code was written in the past and why, and help us make good decisions when functionality needs to change or new features are added.

The cliché that a picture is worth a thousand words applies to software documentation. Mind maps, story maps, flow diagrams, and other visual design and brainstorming tools can be recorded either by using a software tool or simply taking a photo of drawings and including it in the documentation. Screenshots of the UI or reports are good memory joggers, especially if they are annotated.

We use agile values, principles and practices to help us deliver high-quality software that provides value to the business in a timely manner. In agile development, we strive to continuously improve our work. We can’t do that without adequate documentation.

Dig Deeper on Topics Archive

Start the conversation

Send me notifications when other members comment.

Please create a username to comment.