Published on AgileConnection (https://www.agileconnection.com)

Home > Should Stories be kept as permanent system documentation or should requirements be maintained to document the system
Ward Edwards's picture

Should Stories be kept as permanent system documentation or should requirements be maintained to document the system

Ward Edwards asked on March 3, 2016 - 4:00pm | Replies (2).

Should stories be kept in place of requirements to provide permanent system documentation or should a functionally organized set of requirements be maintained as this documentation.     Either way, I am trying to figure out the best way to maintain a description/model of the system being maintained that is understandable to non technical and technical staff and provides a starting point for analyzing future changes to the system.

Brad Appleton's picture

There are some pretty good tool integrations with Wiki's that provide a various nice way of being able to update/edit story descriptions (either in the wiki, or the tool) and being able to organize+navigate a hierarchical "tree" of epics & stories as if it were an online document, as well as being able to generate (or print) a single document from the tree of stories.

 

My favorite way however is in the case where you already know there is a need for user-documentation (e.g., user-guides, online help, reference-manual, admin-guide, etc.). and to have these documents serve double-duty as system/requirements documentation that incremental evolve with each iteration. This may involve "pairing" those who detail the story (and the tests) with technical writer, as well as using practices like BDD and Specification by Example to generate some of the examples used in the user-docs.

Atul Mathur's picture

M2C: Stories are often routed thru Tools and used as an individual tracking to its closure in the pratical scenario. Secondly, complete set of requirments may not be provided in an Distributed Development System Projects. 

IDeally would like the complete set of Requirments to be collated in an system documentation but if it is in the perogative of the customer, then an revision becomes cumbersome.  

My take thereby is to maintain each requirmenets under an stories format and supported by an high level document wherein the interlinkages of the stories and thier identifications are mentioned only to show case the complete set of requirments receivable by the development projects; thereby depicting an wholeistic picture. This becomes the early reference point for tracking changes and revisions to the requirements. 

2 Answers

Atul Mathur's picture

M2C: Stories are often routed thru Tools and used as an individual tracking to its closure in the pratical scenario. Secondly, complete set of requirments may not be provided in an Distributed Development System Projects. 

IDeally would like the complete set of Requirments to be collated in an system documentation but if it is in the perogative of the customer, then an revision becomes cumbersome.  

My take thereby is to maintain each requirmenets under an stories format and supported by an high level document wherein the interlinkages of the stories and thier identifications are mentioned only to show case the complete set of requirments receivable by the development projects; thereby depicting an wholeistic picture. This becomes the early reference point for tracking changes and revisions to the requirements. 

Brad Appleton's picture

There are some pretty good tool integrations with Wiki's that provide a various nice way of being able to update/edit story descriptions (either in the wiki, or the tool) and being able to organize+navigate a hierarchical "tree" of epics & stories as if it were an online document, as well as being able to generate (or print) a single document from the tree of stories.

 

My favorite way however is in the case where you already know there is a need for user-documentation (e.g., user-guides, online help, reference-manual, admin-guide, etc.). and to have these documents serve double-duty as system/requirements documentation that incremental evolve with each iteration. This may involve "pairing" those who detail the story (and the tests) with technical writer, as well as using practices like BDD and Specification by Example to generate some of the examples used in the user-docs.
©2011-2013 TechWell Corp.