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

Wikis and software requirements specification: Tracking changes in Agile development

There are several methods for tracking changes so that all team members understand what has taken place. Read this expert response for Lisa Crispin's take on requirements change tracking.

In Agile methodologies, is it important to track changes being made to requirements? What about when there are verbal agreements? Does someone go back and document the updates?

In my experience, requirements are always a moving target, and it’s helpful to keep a history of what decisions were made and why. Months or years down the road, someone might question why the software works the way it does, and we often forget the reason. A technique that has worked well for my team is to use a whiteboard to draw diagrams and examples as we discuss specifications. We post high-resolution photos of the whiteboards on our wiki for future reference. We can look back at these to see how requirements changed.

For a complex new project, we record design discussions on a wiki page, posting questions and answers as they come up. We’ve often referred back to these wiki pages to remind ourselves of why we went with a particular alternative.

Distributed teams may prefer to use online collaboration tools that simulate whiteboards or index cards. Before you choose a tool, you may want to make sure there is a way to record the history of any changes made to user stories.

Specification by example (also called acceptance test-driven development or ATDD), where you turn customer examples of desired and undesired behavior into executable tests, is one of the best ways to document a software system. These should be checked into the source code control system, making it easy to see the history of changes over time. Once the tests pass, they go into a regression suite to be run with the continuous integration process. Since the tests have to keep passing over time, a failure may signal a change that was purposely made to the system behavior, and the test must be updated. This ensures that the documentation is kept up to date. As Gojko Adzic told me, business people may resist allocating resources to updating test automation, but they are more likely to understand the need for keeping documentation up to date.

Changes to requirements often happen in casual hallway conversations. Be sure to capture these to share with the rest of the team and keep a record in case questions come up later.

Dig Deeper on Topics Archive

Start the conversation

Send me notifications when other members comment.

Please create a username to comment.