More specific we document:
- User stories, to justify the need for a piece of functionality and to steer the project
- Acceptance criteria, as a test base and to give more functional detail to a piece of functionality
- System test scripts, to be able to check regression and to help document more technical decisions
- Service definition, to describe the functionality needed for interfaces to more technical parts and third party interfaces.
Using User Stories for documentation is not a straight forward process. I wonder whether the set of User Stories you use on your project, sufficiently describe the functionality of the system. I also wonder whether maintenance personnel, not initially part of the team are able to navigate the user stories and find information they need easily. In my opinion just creating a backlog does not do the trick as the set of User Stories is fairly unstructured. At the start of the project these user stories describe needed functionality and form a good basis for documentation. Later on in the project the user stories also start describing changes to the earlier functionality. If you need an overview of the functionality created you, need to read through all the user stories created about the subject.
To help with this problem, I’ve created a functional structure derived from the application. The user stories created are placed in the proper place in the structure. The structure itself comprises the processes, process tasks and lower level modules that make up the application. The names of the elements in the structure follow the names that users (and thus maintenance personnel also) find in the application (ubiquitous language). The development team links every User Story to it’s place in the structure. The result is that the User Stories can easily be found back by maintenance personnel. This enables the maintenance team, but also the development team and implementation team to retrieve the information put in the user stories and acceptance criteria. As for user stories, the structure can also be used for the system tests or any other documentation you feel is needed for maintenance.
You may ask yourself what tool is needed to create this structure? Requirements management tools are capable of doing so. The problem with these tools is that they come with a price and a learning curve. The question is, is there an inexpensive tool that is easy to learn and easy to use?
I’ve been able to create just that: Using open source MediaWiki with CategoryTree plug-in my team is able to document the software on those parts that are not covered by the BPM suite models. Creating a sprint, adding User stories, placing these user stories in the right place of the skeleton is easy and straight forward. Navigating the structure by the maintenance team and others involved is easy and follows the structure of the application itself. Adding test scripts, storing test results and documenting service descriptions in the structure is as easy.
Working with a wiki adds to the agility of the team as it is light weight, flexible and does the job well. Working with a wiki is more easily accepted by Agile team members then more elaborate requirements tooling.
What I’ve created is a structure for documenting software in an agile manner. I’ve created a help page with templates and guidelines on how to use this wiki. Please contact me if you’re want more information or want to get the wiki pages enabling this structure. I can help you and your team to implement this way of working, giving them a way to document for maintenance purposes.
