Archive of Software requirements specification Articles

How do you approach starting a small requirements project as part of a large initiative within a massive enterprise? Do you boil the ocean? Your customer knows she needs “requirements” to give to her development team. She asks you - what will you deliver, and how long will it take? Great questions. If you have to write a statement of work, with time/cost estimates, and a list of deliverables - what would you do?

What is the right level of detail for writing requirements? What about for writing specifications (functional, non-functional requirements, etc)? The answer is that there is no one answer. But there are guidelines, and reasons to write more detail, or less detail - for any given product or project, and any given team. The reason we write requirements is so that they can be read. Understanding the readers is the key to determining which details to include in the requirements.

Almost a month ago, we published an article titled Broken Requirements Ecosystem. That article built on a discussion thread at Seilevel. Since that time, the original thread has grown, and a new one has been spawned at the Catalyze site.

In short, the question was asked on the Seilevel forum- why are specs sometimes ignored by developers, and four possible reasons were suggested.  We followed up with our view, and the discussion picked up again, this time at Catalyze.

1. Original discussion thread on Seilevel’s forum: Reasons Reqs Go Unread (Discussion from 19 Jun to 26 Jun )
2. Article at Tyner Blain: Broken Requirements Ecosystem (Written on 21 Jun, Discussion to 26 Jun)
3. Thread spawned on the Catalyze forum: Broken Requirements Ecosystem (Discussion from 23 Jun to 15 Jul)
Note - the dates above for each article/forum-post are as of right now. People have submitted 23 comments across the articles, showing a lot of good insight from many different perspectives. Developers, product managers, project managers, stakeholders - lots of great comments!

Even if you read our article before, go back and follow the discussions again - starting with Seilevel’s article, and progressing to ours, following up with the conversation at Catalyze.

There’s an interesting thread on Seilevel’s requirements forum about why developers don’t read the specs and how to fix this problem. Sometimes the developers throw away the requirements. And that’s bad. But it is a symptom. Something is broken at a higher level.

With a definition of the important use cases for our agile project, we can move to the logical next step - which is what exactly?

Prototyping.

There are 15 ways for someone to shutdown a laptop running Windows Vista. This adds unwarranted complexity to our software. How can we avoid the same problem in our software?

“Why?” The question is our inspiration and our muse. “Why?” is the justification for our requirements. The key to identifying “What?” and “When?”, which lead to “How?” and “How Much?” But there is another use for “Why?” - communication of intent (with stakeholders and implementers). Requirements documents are artifacts, but they are also dynamic documents. By documenting “Why?” a requirement is a requirement, we make it easier for future readers to understand.

The reason we write is so that someone can read it in the future. Duh. When we’re writing requirements documents, or documenting processes, how often do we stop and think about who will be reading our documents? We need to make sure our writing will be easy to read for our audience.

James Kovacs shares a great insight on software testing and the software testing process. His epiphany about test driven development makes it obvious to all of us why this technique is so powerful.

Giving a functional spec to developers and testers is not sufficient for creating great software. To a developer, a spec is only the what and not the why. And for a tester, the software requirements specification is neither. Use cases provide the why that explains the intent of the system for the implementation team.