Open question: Should requirements be an itemized list/database of statements or a storied theory-of-operation document with diagrams, tables, formulas, etc.?
This is a more of a philosophical question rather than a SDLC process question (though if someone has a process that addresses this scenario – I would love to hear about it). I’ve found that a theory of operation document (aka a story) provides context and enables my understanding of the project as whole. Whereas an itemize list of statements is essential when it comes to verifying that software has met the requirements. My dilemma or claim is that a project needs both, but then there are two sources for requirements. Which leads to keeping the two sets in sync and when they differ – raises the issue of which source is the canonical source. Not actually a win-win situation.
What has been your experience? What has worked well on your project(s)? What has worked poorly?
What typically happens for me
At the end of a project we have an itemized list of requirements statements that we use for software verification and it is the canonical source for requirements. In addition, there is a collection of documents that are the origin of many of the project requirements – but are no longer actively maintained. However, these documents are kept around because they are invaluable for onboarding new team members and for data mining the original intent of requirements. Eventually these documents become so out of date that they stop being a positive asset. At this point, the organization then relies on tribal knowledge for retaining the theory-of-operation. The problem with tribal knowledge is as tribe members come and go, for each membership change knowledge is lost, diluted, or both. This scenario is manageable if the software/project has life span of only a few years. However, I work in the embedded space where it is typical that the software/product life spans are measured in decades.