Home | Login | Recent Changes | Search | All Pages | Help

WhatDoYouLiketoSeeinaRequirementsDoc

I'm at a client this week, doing an assessment. I'm looking at their requirements documents, and here's what I've discovered:

  • They're trying to make a requirements doc serve the customers, the developers, the testers, and the trainers (the people who train the customers to use the system)
  • Their requirements documents are ambiguous and full of implicit requirements (if you know how a system like this works, you wouldn't find them ambiguous -- maybe
  • Their requirements documents regularly run 75-100 pages long

I'm beginning to think there is no such thing as a generic requirements document. This will be the 10th or 15th (or ??) client for whom I've suggested a customized requirements document that fits their needs.

Why do people not think about their requirements for their requirements documents?

Why do people think they can use a StandardDocument for anything, including requirements?

What do you like to see in a requirements document?

JohannaRothman 2005.02.14

Why do people think they can use a "standard" document for anything, including requirements?

I suspect we hope that the standard will allow us to focus on the meat , the requirements themselves, rather than the structure of the document. I have experienced the opposite. Given a fixed structure, the arguments about what that fixed structure is or should be dominate. Then again, I haved experienced the same without a fixed structure. Fixed structure? No fixed structure? Where's the third choice? -- MikeMelendez 2005.02.15

Johanna Rothman asks Why do people not think about their requirements for their requirements documents?

Let's give them the benefit of the doubt. Perhaps their requirement is to have a requirements document. And the measurement of success is a big thick document rather than its contents.

If you want to know why requirements documents are the way they are, explore the history of requirements documents at the company.

Johanna Rothman asks What do you like to see in a requirements document?

Tough question.

Lucid writing. A specification that tells who the intended reader is for the document. Evidence that the problem has been thoroughly explored. A structure for the document that is congruent with the the problem space. Evidence that the document has been reviewed. A list of problems that won't be solved. Signatures. An index. A glossary of terms.

Johanna Rothman asks Why do people think they can use a "standard" document for anything, including requirements?

Come on. You know why.

SteveSmith 2005.02.15

One thing I always want to see, and almost never do, is WHY each requirement is there. That's one standard about requirement's documents that I would require in every one.

The absence of WHY explains in great part why we always thing requirements are changing, and why we're always surprised when they chance. Since we don't know why they're there in the first place, we don't see the changes coming. - JerryWeinberg 2005.02.15

Steve,

Actually, I don't understand why people think they can use a standard doc, such as a template for requirements (or anything else). I think of templates as a technique to help me remember why I'm writing this thing down. But if it doesn't work, I change it. What I don't understand is why other people don't feel free to change their templates. I hope you explain it to me. -- JohannaRothman 2005.02.16

Jerry, can you talk more about the WHYs? Do you mean for which user, to enable that user to do what thing? -- JohannaRothman 2005.02.16
Mike asks, " Fixed structure? No fixed structure? Where's the third choice?"

Oh, what a great question. I don't know. Maybe an adaptable choice? Maybe a set of possible structures, so people have to choose from among the structures to fully represent this project's requirements? I've been designing requirements docs with my clients to help them write down their requirements. I start with the users. "What does that-kind-of-user need to see? Are their needs different from the other users?" We generally get to a doc that can be used most of the time, except when it can't :-) Does that make sense? -- JohannaRothman 2005.02.16

Jerry had an interesting typo (I think it was a typo).

requirements are changing, and why we're always surprised when they chance.

He typed "chance" instead of "change."

I think there is probability or chance associated with any requirement and requirement change.

Why don't people change their templates to meet their situation?

Because they will have their fingers slapped with a board. Sometimes that board is a Board (i.e. group of people at a review meeting). Sometimtes that board is a piece of lumber.

DwaynePhillips 16 February 2005

Johanna Rothman writes Actually, I don't understand why people think they can use a standard doc, such as a template for requirements (or anything else).

The belief that a common format reduces variation and thus, by all the laws of process improvement, creates a superior, measurable product (document). ;-)

SteveSmith 2005.02.16

I agree wholeheartedly with Jerry on the "why" question - and would probably go further (as Ricardo Semler of Semco would) and ask the five whys. A conversation may go something like this:

Q1. why do you have this performance requirement of 5 seconds? A1. because I asked the sponsor how fast it has to be

Q2. why did the sponsor tell you 5 seconds? A2. it was probably the first figure that come into their head

Q3. why didn't you ask other questions to find out the real requirement? A3. because I don't know what questions to ask

Q4. why don't you know what questions to ask? A4. because I've not had any training to do this job

Q5. why haven't you had the training to do the job? Q5. because I've never thought to ask

PhilStubbington 2005.02.17

I often type "chance" for "change." I was a great insight of mine--one that Darwin had more than a century ahead of me.

As for the Why, here's what I suggest. Take some requirement statement from any document you're using and as an exercise, add the context and see how your mind wraps around it and understands more. We did this, in fact, yesterday at a client. They had a complicated requirement to identify hardware components in such a way that you could distinguish between operational parts of the system and support parts--like test drivers and monitors. They were going to do this by a unique numbering system, but then we asked why they needed to distinguish them.

Well, it was because when an alarm rang, the operators had to be able to pull off all and only the support parts quickly and reliably or people would die. Oh, someone said. It turns out, they were going to put these uniquely distinguishing identifiers on metal plates on the bottom of each component. Some of the components would require four people to lift. They decided instead (or in addition) to paint the components different colors. Until they knew why, they couldn't see how totally unresponsive their solution idea was, although it certainly met the requirement as written. - JerryWeinberg 2005.02.17

What do I like to see in a requirements document? The right conversations happening around it.

I have no particular objection to any of the various forms / formats for capturing requirements, or for stimulating requirements exploration. I do object sometimes to the implied conversations that go with the various formats - who gets to participate, what can be discussed. From IEEE template-heavy SRS to CRC cards, I embrace any or object to all, depending on how the ritual of the format excludes or includes concerns and stakeholders important to the success of the system.

At my current client, I'm working with router software (& stuff). It turns out that some parts, especially a key new feature under current development, are completely UI and user experience oriented. So for that, we went from functional / behavioral component specs, through use cases, to a kind of storyboard prototyping, which right now is singing along. I'm pretty sure for RFC compliance a storyboard will be nearly useless, "use cases" have a bit of an impedence mismatch, and "user stories" don't capture some very important stuff well. I'm just as sure that for these particular features of the moment and getting the right concerns and stakeholders to participate fully, storyboards are working better than anything else we tried.

We're still managing the story boards (and the earlier use cases) like a document. It's one representation, with shared visibility and change management (meaning notification and agreement vs. having a "formal impediment group" to reject necessary changes.) Managing it as a document is also helping the right conversations happen.

-- JimBullock 2005.02.18 ("I came here for an argument." "No, you didn't." - from Monty Python's Flying Circus)

Here's one thing I don't like to see in a requirements doc, prompted by Jim's interesting narrative about storyboards: lovingly detailed screen mock-ups, which obviously took hours of painstaking work with Photoshop or some such to produce. I'm totally distressed whenever I see that - it reminds me why people used to be passionate about RAD tools, and sad that their days in fashion came and went in vain.

-- LaurentBossavit 2005.02.21

I'd like to generalize on Laurent's note, which I very much like. One of the problems I have when collecting requirements ideas (I like to call them preferences) is that engineers have a tendency to present a design (e.g., Laurent's detailed screen mock-ups). That is, they tell me how to solve the problem they have in mind, rather than what the problem is. Given that the final set of preferences included in the requirements has not yet been chosen, design as part of a preference collection is premature. -- MikeMelendez 2005.02.20
Laurent and Mike, one of the reasons do these detailed mockups is that (sometimes) they literally can't imagine what the system would look like, so they can't define their requirements. What do you do to help people understand their requirements (as opposed to their design of what the requirements might lead to)? -- JohannaRothman 2005.02.22
Two parts to my answer. First, "requirements" and "what the system will look like" are two different things. I have written a (still incomplete) RequirementsReverie that I'll post here soon, delving into that a bit deeper.

As to the second part, it's not so much a question of "what do I like to see in requirements" but, a la Jim, a question of "where do I like to see the requirements conversation happening".

I like whiteboards. A whiteboard is a useful place for a conversation about what a given bit of UI will look like. It's much faster to draw the UI than to mock it up with software, and more importantly you don't feel troubled at all by erasing and redrawing parts of it until you really understand what's going on. When you're done, take a picture of the whiteboard.

If the team is using a RAD tool, then it probably makes more sense to "capture" what was decided at the white board as a RAD form - that's what it needs to end up as anyway. One risk with RAD tools: in a team where I attempted to introduce "whiteboarding", they went right on doing what they did before - having the developer themselves "design" the UI directly in the RAD tools, alone at their computers rather than in conversation with the product managers.

-- LaurentBossavit 2005.02.23

I like whiteboards too, and I like the giant sticky notes or even flipchart paper even better, since you can post many of them around a room with few or even no whiteboards. And take them elsewhere to work on later.

I find that if I am given a "requirements" document, it is often really a functional specification. While I like functional specs, the 2 are not the same.

SherryHeinze 2005.02.23

I agree with both Laurent and Sherry. It's a matter of dialogue. Whiteboards, sticky notes, even backs of envelopes work when you're trying the pin down what the problem is you're trying to solve. But it has to be a dynamic process. When I'm collecting preferences and I get a design, I start a conversation trying to get to the what of the problem. When I think I have it, I feed it back to the engineer as a what and see if the engineer agrees.

In a spirit of "write first, read later", I just reread the full page. It seems to me, Jerry has the key question to ask -- Why? -- to get at the what. To sum, I need to know what the problem is before I can judge what options might work to solve it. As important, I need to generate multiple options on the solution so I understand the trade-offs, but that's the next step. Here it just serves as a marker to remind me not to "solve" a problem too soon.

To bring it full circle, maybe the Requirements Doc needs to spell out the problems that it proposes the requirements, if implemented, will solve.

MikeMelendez 2005.02.23

" . . . the Requirements Doc needs to spell out the problems that it proposes the requirements, if implemented, will solve."

Nice.

Many of the errors in software methods and methodologies come from forgetting that building software is an instrumental activity. It's always "in aid of" something. Forget that, and you can spend all your time mocking up a screen without involving the people who will use it.

Software isn't "right" because it is made a particular way, it's right only in terms of it's utility (intended or accidental.) Similarly software methods - including requirements methods - are right only in terms of their utility in producing software with particular utility.

Concretely, I think four things apply to nearly every example of software requirements: multiple kinds of representations of system behavior, traceability from problem to proposed solution to proposed implementation, "coverage" of some kind and most important, the people who agree that this represents the conversation they had, at least well enogh to proceed.

-- JimBullock 2005.02.23 ("It's not a commitment. It's more like a goal.")

I just went through a redesign of our architecture spec document and I think the process and result could apply to requirements docs, as well. In a lot of conversations with a lot of people with different roles collecting requirements. (Aetna is a large organization). The strategy led us to a 3 part document: 1) an executive summary (up to about 15 or so pages) which could be read by reviewers, managaer and anyone wanting to wrap their brain around the architecture recommended, the risks, and the rationale; 2) the architect's take on the requirements (functional and non-functional) and any added refinements; 3) the guts of the design organized by application view and service or reuse parts.

I agree that too much standardization produces the wrong thing. Previous architecture documents were running 75 - 200 pages (Ack!). I also agree with the intent-driven synopsis that Jim posted.-- BeckyWinant 2005.09.13

I like a lot of XP thinking when it comes to requirements.
  • If 80% of requirements are never used/implemented, they're clearly not really requirements, so lets not call them requirements. XP calls them "stories".
  • Many projects I've been involved in use a standard form for stories which captures Jerry's "why" question quite well, I think: "As a <role> I want <feature> so that <context>". That's more formal than I'd like, but some teams need that level of formality.
  • XP actively encourages changes in requirements. If the business landscape changes, the business needs change, so the software team that can adapt to that brings increased revenues for the business.
  • There's no such thing as a non-functional requirement on an XP team. "As an Account Manager, I want the system to be able to handle 100 requests per second, so that I don't lose customers to timeouts"
  • The feature request is comprised of 3 parts - Card, Conversation, Confirmation. The index card is the "As an X..." text above. The conversation is a discussion that happens around that card between the technical team and the "customer". The confirmation is a set of acceptance tests specified by the customer as "competion criteria". All three parts are needed for a story to be considered elgible for implementation.
  • XP has two distinct roles embodied in the customer - The Gold Owner and the Goal Donor. Everything works well when both rles are served by the same person. Things get complicated when the entity specifying the product and features is distinct from the entity paying the bills. The Card/Conversation/Confirmation happens with the Goal Donor, but if the Gold Owner has different ideas, trouble ensues, as normally the Gold Owner is less available and higher-ranking.

--Alan Francis 2005.09.16

There's nothing wrong with calling a requirement a requirement if it really is required. - jb

I've had a great deal of success with flushing out what's really "required" with three techniques:

  • Force-rank the big list. You can try ranking "by value" but this begs the question: "Value measured how, by whom?" I prefer to ask for ranking in terms of: "In what order do you want this stuff?" and to do so in a conversation with all the stakeholders represented together. For me, force ranking is one of several useful organizations of what is essentially the same pile of information about what a system might do.
  • I decline to "release" something that doesn't include all the requirements. If we're willing to ship it without those things, get them off the "required" list. This works with increments, and with bundles of increments that ship more broadly.
  • Ask, with each increment: "What do we think makes a good chunk to release next? Is this the thing?"

There is often a whole lot of activitiy & communication that goes with putting a new system or version in front of all the people who will use it. Most of them are not, indeed, co-located with the development team full time. I think these folks are another constituency for the "requirements document" or for information derived from it (in whatever form.) At a minimum they legitimately want to know what's going to be different for them with this new system or version. What can they expect to change? Count on changing? Count on not changing?

We ought to pay attention to "requirements" as part of the delivery of the system once built, as well as input to the process of building the system.

-- Jim Bullock 2006.09.16 (Are we done yet?)
One of the benefits of working from "stories" that the stakeholders rank (and re-rank on a periodic basis) is that it's possible (though not always easy) to draw a line that separates "what we're paying attention to now" from everything else, and another line higher up that separates out "what we're intending to deliver now". It doesn't matter if some of what's below the "interest" line is fantasy or nonsense; that'll get resolved if and when those stories bubble up near enough to the top of the list to warrant attention. Meanwhile, the development team be focuses on a finite, bounded chunk of work without getting side-tracked by grand visions.

This approach also lets customer hang on to some of their fantasies in a way that doesn't let those fantasies interfere with what's worthwhile now.

--DaveSmith 2005.09.16

The thing that I want most in a requirement (whether it's in a document or in somebody's head or gut, is understanding. I want to customer (goal donor and gold owner) to understand what it is they're asking for, and I want the implementors to understand what they're being asked to produce, and I want the two understandings to be the same.

So, as a means to that end, I want the requirements to be expressed in a mutually understandable manner, and I want the requirements process to be executed in a manner that demonstrates that understanding, and fosters it if it doesn't currently exist, and corrects it if it slips away. As far as I'm concerned, any process that does this, any documents or whatever does this, is just fine with me. And any one that doesn't, is not fine with me. - JerryWeinberg 2005.09.18

I thought I said that.<g> Apparently not, providing a fine example of what can go wrong with requirements. I meant to mean exactly that. Whatever I said (above) did not parse that way. Sigh. Back to writing school. - jb
For me, I find the table of contents the most important thing. A well structured one will at least remind me of the things that I ought to consider. We've had some success using the Volere template from SuzanneRobertson and JamesRobertson of the AtlanticSystemsGuild. The discussions about its usage have been very interesting - not to mention amusing - along the lines of "it doesn't do this", "I'm not sure what that diagram tells me", "it doesn't include business process", etc. I'm sure we've all seen blaming applied to a inanimate object, haven't we? At least they don't answer back.... <g>

Standard documents are both a blessing and a curse (like BestPractice) - they save you recreating the mundane, and save you from engaging brain.

PhilStubbington 2005.09.20

Updated: Tuesday, September 20, 2005