Keith Collyer
2 min readOct 16, 2023

--

Excellent article. A few comments. I agree with pretty much everything you write except the last paragraph.

I'm a great believer in "Just Enough Documentation", which I think is pretty much what you are advocating. I do think that for any but the most trivial system there is value in collating the requirements into a single document, otherwise some will be in separate documents and some in Jira Description fields. This has the great danger that inconsistencies will inevitably be missed. My beliefs are very much in line with the approach advocated by David Parnas in his classic paper "A Rational Design Process: How and Why to Fake It", which I recommend anyone involved in product definition to read.

Despite starting in software over forty years ago, I've never worked on a "waterfall" project. Waterfall as commonly interpreted is, I believe, a strawman invented by the authors of the Agile Manifesto to pitch against. Royce's original paper (which never used the term "waterfall" made it absolutely explicit that stages were at the least iterative and you should expect to go back and revisit earlier decisions. In many ways, it was more agile than Agile!

Along with a requirements document, create a project dictionary. Little causes more confusion than having several terms for the same thing or, even worse, several meanings for the same term.

In the interests of disambiguation, "carat" should be "caret" ;).

My personal preference for the Ohio State examples is that the requirements should be linked to the rationale, as many times the same rationale spawns multiple requirements.

I like the idea of separating Stakeholder Requirements that describe what the stakeholders need to achieve, from System Requirements that define what the system must do. Ideally, these should be in separate documents. Your last paragraph states that the Software Requirements Specification details "how a specific something should be built". I disagree with this, it should specify what the something does. The Design (or Architecture, if that is needed depending on the complexity of the solution) specifies how it should be built.

--

--

Keith Collyer
Keith Collyer

Written by Keith Collyer

I’m a husband, father, grandfather, retired Systems Engineer, bassist, cyclist and will write on any and all of those things as the urge takes me.

Responses (1)