Software Requirements Specifications (SRSs) are documents that can be helpful in laying out exactly what an application needs to do. They are especially helpful at the beginning of a project to get everybody on board and agree to some basic metrics for success (i.e. if the application does not do ‘X’, then it is not complete). Often, as soon as the document is translated into an issue tracker or broken down for work by the development team, it quickly loses relevance. People are swamped with keeping the project moving, that they sometimes are unable to edit and maintain critical documentation. By the end of the project, some are still held accountable for features in the SRS that everyone agreed were changed, but the changes were never documented.
One can actually write the SRS as cases in an issue tracker. Using issue tracker APIs, the requirements can be dynamically pulled out in its current state and packaged as an always-up-to-date document for better readability. For some, it does not make sense to have to read through the issue tracker, but read that data in a digestible format such as a document. Once in the issue tracker, all cases can be directly attached to the parent requirement. No cases should be orphaned from a parent requirement. If a case does not trace back to a requirement, chances are it is extraneous to the development effort.
Below, I will walk through the process of pulling the requirements out of FogBugz and writing them to a local disk in Markdown format.
Traceability
A key component in planning a development project is tracing the actual features developed back to requirements specified. Essentially, features should be justified by fulfilling specific requirements. If you are going to build a user account on a website, why? What is the requirement that drives the need for a user account? If there is no requirement, then do you really need to spend the time to develop user accounts? No. Spend effort where it will gain a return.
During the planning and reporting process, traceability is used to map the requirements to decomposed features– justifying the work actually being done. In traditional documentation methodologies, a traceability matrix is used to bridge the gap between an SRS and a design document or work the developers are actually performing. Unfortunately, a gap exists. A bridge is needed. Ultimately, this indicates a potential for duplicated work at best and a full time job to maintain at worst.
Traceability breaks quickly as an SRS is not maintained, or as the pace of the developers picks up speed or pivots or for a variety of reasons. Traceability is important to help maintain a cohesive vision and maintain accountability throughout the project.
Maintaining all requirements in the issue tracker from the beginning of a project allows full transparency and traceability for developers and project managers. Features can be marked as sub-cases of specific parent requirement cases. Bugs or research or other tasks can be entered as sub-cases to the parent requirement case as well. In this manner, a developer working on a specific case down the tree can always follow the tree back to better understand why and how this case fits in with the development effort.
Dynamic
Pulling requirements from the issue tracker is a dynamic process. Whenever a requirements document is pulled from the issue tracker, it is pulling the current version of the requirements. In FogBugz, the script will only pull the most recent event (block of text) of a Requirement case. Once the data is changed, a user can manually trigger the script, or the script can be automated in a fashion to fit the needs of the organization’s workflow.
Requirement history
Looking at the case detail will show the history or commentary and entries for the content of the requirement. A user can see exactly how a requirement has changed over time. If the users document why a change is made, they will also see the justifications (or rationalizations) for the changes. If a version control system like Kiln is a part of the workflow, then the history can also be stored in the changesets. The ability to view the historical change of requirements allows a user to go back to any version of any requirement at will. This can be done for an individual requirement at the case level, or for an entire document at the version control level.
Set Up
This process hinges on a few features of an issue tracker. FogBugz allows a user to create custom case categories. The defaults are: Bug, Feature, Inquiry, Schedule Item. Add “Requirement” as a category. It is helpful to also add custom statuses for the new category.
Active Status:
- Proposed
- Approved
Resolved Status:
- Implemented
- Duplicate
- Removed
- Void
- Verify
Customize the category and statuses to better fit the workflow at the organization. Within FogBugz, existing projects can retrofit to work with this method; designate a “Requirement” case as a “Parent Case” of other existing cases.
Markdown
The comments in the Requirements case are kept in Markdown format. In this way, they are ready to be incorporated into an overall Markdown SRS as atomic chunks of requirements. If a requirement changes, one only needs to edit one piece as opposed to the whole document.
I chose Markdown because it is plain text. When the source is plain text, it can be versioned efficiently, moved around to different tools effectively, and output to many different formats. The documentation system I have set up for our workflow will output our versioned SRS, design documents, technical documentation, etc. to HTML on an internal site for internal consumption, a PDF for client delivery, and a Word file.
Python Script
The Python script that controls everything is rather simple. It can be found on my GitHub site.
The script requires you run pip install fogbugz.
The script consists of three primary functions:
- Get the cases from FogBugz
- Translate the XML to formatted Markdown
- Writes the Markdown to a file.
All the script needs to run is the location of the FogBugz instance, a valid token, and the name of a valid project.
For my plain text documentation workflow, it is critical this whole process can be automated and tied into our build server and automatic “build” actions for our documentation repositories.