Category Archives: Software requirements specification

The artifacts we create when managing requirements, the process of creating them, and how to use them. The SRS is one of many requirements models. It specifically documents the details needed by an implementation team to guide the development of the software product.

Atomic Requirements

Each requirement you write represents a single market need, that you either satisfy or fail to satisfy.  A well written requirement is independently deliverable and represents an incremental increase in the value of your software.  That is the definition of an atomic requirement.  Read on to see why atomic requirements are important.

Continue reading Atomic Requirements

SRS Plan of Attack

boiling water

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?

Continue reading SRS Plan of Attack

Requirements Details – How Much is Enough?


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.

Continue reading Requirements Details – How Much is Enough?

Ignoring The Requirements, Watching The Discussion


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.

Broken Requirements Ecosystem

throwing away

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.
Continue reading Broken Requirements Ecosystem

APR: Mixing It Up With Design And Requirements

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


Continue reading APR: Mixing It Up With Design And Requirements

Fifteen Ways to Shut Down


[Updated Below] 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?

Hat Tip

Joel (on Software) has an article where he lambastes the Vista team for providing 9 different ways to stop using the computer. Add in the hardware options on the laptop (like Fn F3), and closing the screen down or hitting the physical power button, and you get to 15 different ways to shut down.

Inevitably, you are going to think of a long list of intelligent, defensible reasons why each of these options is absolutely, positively essential. Don’t bother. I know. Each additional choice makes complete sense until you find yourself explaining to your uncle that he has to choose between 15 different ways to turn off a laptop.

Joel Spolsky

Make Everybody Nobody Happy

Joel posits that the unreasonable number has grown out of the desire to make everybody happy. We know that too many features makes everyone unhappy. This bloated list of choices is just one manifestation of too-many-features, and it doesn’t make anyone happy.

Inadvertantly Causing The Problem

It is pretty easy to imagine how we might inadvertantly cause this problem.

A structured requirements approach allows us to track and manage different requirements, as well as the implementation of those requirements. In Joel’s example, imagine requirements like the following:

  • User secure the computer in order to walk away from it without other people getting access.
  • User can shut down the computer such that it will stop consuming power.
  • The computer will support rapid switching from one user to another.

Each requirement could drive an independent solution approach. As Joel points out, each requirement, evaluated in isolation, may lead to a different solution. The problem is that we are finding local optima, and not looking at the problems introduced by the complexity of supporting all of these solutions.

Avoiding This Problem

How can we avoid this sort of problem in our own product development? A holistic view of the proposed solution is required to assess if there are too many features. Prioritization of those features will help us reduce the number to a reasonable level.

Incorporating elements of interaction design into our solution approach may be the best way to do this (short of abandoning a structured requirements approach).

ID and Structure

Each of the shutdown scenarios leads to a functional requirement. Each element of program design leads to one of the many ways to shut down or lock or restart the computer. Addressing the personal goals of each persona provides us with a cross-feature, holistic perspective. If our target audience includes Joel’s uncle, then we can make sure that our design approach accounts for the appropriate level of complexity and choice.


Moishe Lettvin, one of the developers on the shutdown team for Vista, formerly at Microsoft, has written an article about the organizational and situational challenges faced by the team. He titled the article The Windows Shutdown Crapfest. That should give you a feel for how the now-Googler feels about the experience. There were 43 people involved, and they spent over a year. And the source code control system was frightening. Check out the comment thread on Moishe’s article too – it includes comments from other Microsoft and knowledgable anonymous people. Hat Tip to Scoble. Also, a followup from Moishe.

Multiple requirements can lead to multiple, locally-optimized solutions or features. A holistic view needs to be taken to assure that we aren’t introducing too much complexity with these variations of similar features. Interaction design gives us a big-picture perspective to make sure we aren’t making our software too hard for our target users to use.

Another Use For ‘Why?’

Man Asking Why

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.

Meeting Debriefing

I was observing a meeting earlier this week where a member of my team was reviewing a “finalized” requirements document. The requirements in that document were gathered previously, and validated for both correctness and completeness. This review, another step in the elicitation process, involved stakeholders who were not involved in previous sessions. The meeting was not an efficient one.


Over the course of two hours, the team reviewed and discussed no more than ten requirements. The project is a migration project from a legacy system to a new solution. There are minimal process changes in this phase of the project (and therefore the review is looking minimally at process re-engineering).

The following are some of the questions asked by participants in the review:

  • What is the difference between those two [variations of] start dates?
  • Why do we need that information in the system?
  • Why can’t we simplify X to Y?

The answers to these questions (each was asked multiple times about most of the requirements that were reviewed) generally involved relatively detailed explanations, hypothetical examples, and occasional diagramming of business object relationships to effectively communicate why the existing requirements had been written, and why they had been written in the way they had been written.


At the end of the meeting, one of the project sponsors expressed concern that a “final review” meeting was so ad-hoc and disorganized. Our sponsor now has a fear that requirements are being missed, or documented incorrectly.

Anecdotally, there were no significant changes to those requirements as of the end of the meeting. Why did we have to spend 20 man-hours to make no perceptable changes?

Because we didn’t document the answers to these questions the first time!

Document Creation

The creation of, and initial validation of the requirements document involved interviews, contextual inquiries, and side-by-side comparisons and gap-analysis with existing process documentation. The resulting requirements were documented.

All of the questions that were raised in this meeting had been raised in previous sessions. None of the answers had been included in the documentation. And the overall project is large enough, and complex enough that people inconsistently remembered or completely forgot the justifications for the requirements.

Documenting Why

Including the justifications, scenarios or examples, snippets of business object models, and other supporting information would have prevented much of the debate. If we had included the underlying “Why” data that drove the “What” data (the requirements) in our documentation, we would have avoided rehashing these same issues.

It isn’t enough to ask why during elicitation – we have to document the justifications along with the requirements.

Writing For The Purpose of Reading

writing pen

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.

Writing As Marketing

Sam Decker makes a great point about how marketing should use the language of the customer in his recent article. This is actually the 11th in a great series on marketing, if you aren’t reading Sam’s stuff, you should be.

Hit the bulls eye by writing in the language of the customer. To use the same terms, phrases, and straight-forward speak that a customer might use when asking someone else about your solution (and of course, they probably didn’t use the word ‘solution’)!

Sam Decker

Applied To Requirements

Product Managers and others in the “requirements space” all create requirements documents. We create different documents to achieve different goals. It isn’t enough to target our communication content for our audience – we also have to think about the vocabulary we choose to use.

As requirements people, we tend to be precise in our use of language – avoiding ambiguity at all costs. When offshoring, or dealing with multi-cultural teams in general, we also have to understand when terms have different meanings for different people. We also have to watch out for terms that have symbolic meaning, that suffer from varying interpretations.

This precision can come at a cost if we don’t take into account the domains of expertise of our readers, and the terms that they know. As Sam points out, we want to use the language of our audience when describing something.

This can be challenging for pedants like us – when there is a perfectly good, albiet obscure term, why replace it with a sequence of more common words? It goes against our nature. We want concise documents. But clarity (for the reader!) should not be sacrificed for brevity.

Applied To Process Documentation

In addition to documenting requirements, when we are working as business analysts, we also usually have to document existing processes. This is really only true for migration projects, but those represent almost all single-customer projects.

We should make sure that our documents use our customer’s terms when documenting these processes – not our own terms. The responsibility is ours to translate from the single-customer language to the multi-customer concepts.

Process documents are reviewed initially by business owners, and are eventually consumed by systems analysts or implementers. Maybe a glossary of terms is required to help a multi-customer implementation team deploy enterprise software for a client. The documents developed for, and validated by the customer should use the language of the customer.

Applied To Communication In General

When we’re in meetings, having conversations, writing emails, or in any other way communicating with our clients, we need to use their language. Product managers should come equipped with a universal translating device. While an initial conversation may start with industry-standardized terms, as client-specific equivalents are identified, the product manager or analyst should immediately create a substitution and use it in all future communication.

We also have to think about the backgrounds of our audiences. Here are a couple stupid things I’ve said in recent meetings with business owners (who have backgrounds in finance and the insurance industry):

  • “From the flow, you can see that the process recurs, and will do what we need.” Translation: The process repeatedly calls itself until it reaches a decision point that forces it to stop. At least I didn’t specify that the process was tail-recursive.
  • “The decomposition of the work is straightforward, we just establish the proper quanta for breaking down the work in each area”. Translation: Break down the work into reasonably sized chunks. What the hell was I thinking?

Pretty much everyone groans when a smug consultant mentions a priori conclusions about prioritization, or an “obvious” algorithm. I’m sure there were a couple groans when I talked about quanta. The use of recursion is even worse – to a programmer, it has a precise meaning. To a non-programmer, it simply means repitition. The dictionary example uses “The cancer recurred” – and I’m sure it doesn’t mean that the cancer cells were attacked by cancer. I actually introduced ambiguity by using a term that some people would find to be more precise (the process was walking down a hierarchical business-data-structure, processing elements along the way).


Thanks Sam for pointing out that we need to speak in the language of our customers. We can extend this idea to make sure we use words within the vocabulary of our audience as well.

Insight Into Test Driven Development


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.


Test driven development is an approach to software development where you write the tests first, and the code second. This sounds ludicrous at first, but it really does work. Here’s James’ epiphany on the subject (emphasis added).

I didn’t understand why TDD practitioner were so zealous about writing the tests first. Why did it matter? I thought it was to ensure that some project manager doesn’t try to shave some time off the project by cutting the unit tests. Then I started doing some reading about TDD, poking around, asking questions, and trying it out myself. I discovered the real reason for writing tests first is that TDD isn’t about testing code, it’s about designing code.

A Tale of Two Epiphanies: TDD and Mocking, James Kovacs

These tests are unit tests, and they are black-box tests (or at least should be black-box tests – read James’ article).

Works Great With Structured Requirements

Not only is this a great way to approach design, but it is a great way to coordinate software development with structured requirements. A well-written requirement describes a need without specifying design. This description then works like a black-box contract. The implementer then must do something that meets the specification given. As James points out, TDD is very effective at creating black-box tests.

This makes sense, when you consider the outside-in approach that comes from starting with requirements. This outside in approach leads to API decisions (for a program or module or method). The API has to support all of the required possible inputs and outputs. Once an API is written, tests can be written.

Best Applied As Part Of Continuous Integration For Larger Teams

All of the tests will fail (because the code hasn’t been written). Then the implementer will write code until the tests pass. Using a continuous integration approach is a very effective way for entire teams to do this simultaneously on larger projects.

Faster Processes

We can also validate the design for completeness prior to creating the implementation. We can compare the generated APIs (and their rationalizations) with the software specification (or application requirements, or FRS… see alphabet soup article). This allows us to address some refactoring needs before the code has been implemented – saving time and money.


Use TDD as an outside-in approach that assures that the delivered software will meet the objectives of the requirements specification. It also saves time and money by supporting validation in advance of implementation.