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.
IMO, requirement traceability and reuse are difficult if they are written in a prose/storied format. A system OpsCon document to describe what the system will do from the user perspective, and why, is helpful in providing the context and overall understanding you mention. Requirements, and the associated rationale for each, are then kept in an RM tool where they can be easily linked and reused.
When it comes to requirement management (traceability, reusing requirements, writing testable requirements, etc.) having an itemize list (preferable in a DB of some kind) is the way to go. And once I understand the system sufficiently – the itemized list works well for me because I can fill in the context from what I already know about the system. So when you talk about a “system OpsCon document” – is this document considered a “design document/output”? Is there tracing from the formal requirements to the document contents? Is it actively maintained throughout the system’s life span?
Sorry for all the questions – but I am looking for something new to try.