Agile requirements documentation can mean different things to different people. Before choosing a tool or format for your documentation, it’s important to know who your audience is and what the purpose of your documentation will be. Tracking story status during development with team members can be very different from delivering handoff documents to clients or product owners. Whatever the reason, you will likely want a tool to help you along the way. In this post, I explore two common methods that can be used for Agile documentation – requirements management tools and wiki-based documentation.
Requirements Management Tools
There are a lot of requirements management tools out there. VersionOne, Jira, Contour, and even Excel could be used to manage user story content. The benefit of these tools is the ability to slice and dice stories for sprint planning, testing, and status reporting over time
If your documentation is viewed as a means to an end, with the end being the actual software, a tool can provide great project management and reporting capabilities. Where it can fall short is the creation of long lasting documentation that provides a narrative of system functionality. When selecting a requirements management tool, consider the level of detail needed for each story, and how changes will be handled.
Don’t Over-Engineer It
When using a requirements management tool, determine how the team will use it in everyday practice. Ask yourself questions like: It is easy to access and update? Will all team members really use it? Loading up each requirements ‘ticket’ with lots of additional or custom fields can ensure that the team won’t fill in the important ones! Also, consider the ability to document vertically – is there a location to enter executable test cases or technical notes?
Remember to Manage and Plan for Change
In an Agile development project, changes or enhancements to previous stories are entered and prioritized as new items on the backlog. When using a dedicated requirements management tool, consider how these items will be connected back to the original story. There may be a traceability option or link within the system, but will all users understand what they are seeing? Would a manager or production support team have to open up multiple items to get the full picture of a piece of functionality?Would exporting the content to Word or PDF require knowledge of the requirements naming conventions?
Wiki-Based Documentation – Supporting Content to Complete the Picture
Requirements management tools often do not give sufficient supporting information within the ticket itself. Additional files have to be attached for a user to get the full story of a feature. Managing lots of static files through the course of a project can get unwieldy. Documents get outdated quickly and take the time to maintain. Instead of attaching documents, I prefer to reference wiki content instead of a document management repository for two reasons: 1) Content flexibility and 2) Collaborative ownership. Depending on project need, the wiki can contain all requirements documentation, or be used in conjunction with a requirements management tool to balance implementation details with status.
Breaking Free from Files
Documents that require opening, saving, and uploading limit the audience and purpose for that content. Anything that may otherwise be created as a Word, Excel, or Image file can be easily transferred to a searchable and flexible wiki. Information may be organized according to the requirements structure, but it doesn’t have to be – whatever is the easiest way for the team to work. Using a reference from a requirements management tool instead of uploading a static file ensures that the most recent version of the content is always available, and someone outside the project team can more easily get the ‘full picture’ of a feature without opening up several attachments.
Team Ownership
A wiki gives the team, instead of an individual, ownership of the information. A document or requirements manager doesn’t have to get everything in ‘the tool’ the right way or create a final document; any team members can create a page and build on it as their thoughts mature.
An incomplete document is better than nothing at all, and may be all that is necessary to communicate a concept. Instead of passing around a file for feedback, stakeholders have the opportunity to provide input early and often, and will be more willing to simply make the updates in the wiki, instead of a document owner having to go back and perfect the document. This saves the team time and creates a more valuable piece of communication.
Conclusion
Requirements management tools, wiki documentation, story cards, or something completely different may provide the best solution for your project and team. The most important thing is that it provides specific value to the project, and contributes to creating the best software solution.
What types of tools have you used for Agile requirements documentation?