Requirements

Nonfunctional Requirements Q&A

~ Andrew Stellman ~ 3 Comments

Non-functional requirements Q&A: We answer questions from readers about using nonfunctional requirements on a real software project, and how to use them on a real software project.

Non-functional requirements: Planning out how well your software will work

A couple of months ago I wrote a post called Using nonfunctional requirements to build better software. It’s basically a step-by-step guide for creating an easy, practical technique to use nonfunctional requirements on a real software project, treating them in a way that’s similar to how a lot of Agile teams treat user stories, scenarios and other functional requirements: by sticking them on index cards and using them to do some lightweight planning.

Since then, I’ve gotten a lot of questions about nonfunctional requirements (or, as some people call them, non functional requirements, behavioral requirements, quality attributes, and probably half a dozen other names). Based on the questions I’ve been getting, a lot of people really seem to want a solid overview of exactly what they are:

  • What are nonfunctional requirements?
  • What goes into a good nonfunctional requirement?
  • Is there a nonfunctional requirements checklist that I can use?
  • How do I write down a nonfunctional requirement? Is there a nonfunctional requirements template I can use?

Luckily, Jenny and I addressed exactly those questions in our first book, Applied Software Project Management, and I’ve gotten feedback over the years from people who read it (and other writing I’ve done about requirements), and tell me it helped them get a handle on the concepts behind nonfunctional requirements. So I’ll do a little requirements Q&A and address those questions one by one, drawing from the book where possible. And I’ve posted an O’Reilly Community blog post called Understanding nonfunctional requirements with some additional information, which should also help get to the bottom of the issue.

Q: What are non-functional requirements?

Non-functional requirements — or behavioral requirements, or quality attributes — describe how well a system performs its function. This is fundamentally different than the typical functional requirements that most of us are used to, which describe what that system does.

Here’s a quick example. Whenever I’m talking about requirements, I like to use a “search and replace” feature in a word processor or text editor as an example, because we’re all familiar with how it works. So while a functional requirement for “search and replace” might describe how the case-sensitive matching works: “If the original text was all uppercase, then the replacement text must be inserted in all uppercase.” A nonfunctional requirement, on the other hand, might describe the performance (“it must be able to replace 1000 search terms in a 3MB document in under 250ms on one of our standard test VMs running at 50% load”).

Q: What goes into a good nonfunctional requirement?

A good nonfunctional requirement is one that makes it clear to everyone on the project — including the user (or someone who really understands what the user needs) — exactly how the software has to perform. Remember, a good requirement (functional or nonfunctional) is about understanding and addressing the needs of a user.

Here’s what Jenny and I wrote about nonfunctional requirements in our first book:

Users have implicit expectations about how well the software will work. These characteristics include how easy the software is to use, how quickly it executes, how reliable it is, and how well it behaves when unexpected conditions arise. The nonfunctional requirements define these aspects about the system. — Applied Software Project Management, p113 (O’Reilly 2005)

It’s really easy for non functional requirements to be unclear or ambiguous. The best way to make sure a nonfunctional requirement is clear and easy to use is to quantify it. So instead of saying that a task must be done quickly, write down the maximum number of seconds it must take to perform a task. The maximum size of a database on disk, the number of hours per day a system must be available, and the number of concurrent users supported are examples of requirements that the software must implement but do not change its behavior.

Q: Is there a nonfunctional requirements checklist that I can use?

We put together a nonfunctional requirements checklist that I’ve used many times on real projects. It’s based on a list of nonfunctional requirements we included in Applied Software Project Management.

Here’s one thing to keep in mind about this (or any other) non functional requirements checklist: as you’re reading it, you’ll probably find yourself thinking, “Wait a minute, all my software needs to be flexible (or efficient, or robust, etc.).” Yes, that’s true, of course. But are there specific non-functional requirements that affect your project in particular, above and beyond what you do on every project? That’s what this checklist is for, and that’s what you should be thinking about when you write down nonfunctional requirements.

  • Availability: Are their constraints on the system’s availability or uptime?
  • Efficiency: Are there resources the system needs to be careful about monopolizing?
  • Flexibility: Will the system need to be altered after deployment?
  • Portability: How easy it is to move to another platform?
  • Integrity: How sensitive is the project to data security, access, and privacy?
  • Robustness: Do error conditions need to be handled gracefully?
  • Scalability: Will the system need to handle a wide range of configuration sizes?
  • Usability: Are there specific constraints on how the users will understand, learn and use the software?

If you’re interested in using this on a real project , you can read more about it in that O’Reilly Broadcast post about non-functional requirements: I post a relevant excerpt from Applied Software Project Management that goes into more detail about each of these.

Q: How do I write down a nonfunctional requirement? Is there a nonfunctional requirements template I can use?

Yes. We put together a software requirements specification template, and I’ve helped a lot of teams adopt it for their own projects over the years. When we put together our requirements templates, we put a lot of effort into streamlining them as much as possible. So this is a sort of “bare minimum” template for writing down use cases, functional requirements, and nonfunctional requirements.

Here’s an example of how we’d specify a functional requirement:

Name Nonfunctional requirement #7: Performance constraints for search-and-replace
Summary The search-and-replace feature must perform a search quickly.
Rationale If a search is not fast enough, users will avoid using the software.
Requirements A case-insensitive search-and-replace performed on a 3MB document with twenty 30-character search terms to be replaced with a different 30-character search term must take under 500ms on one of our standard testing VMs at 50% CPU load.
References See use case #8: Search

And that gets back to the blog post I mentioned earlier, Using nonfunctional requirements to build better software. If you’re working on a team that uses an agile process to build software, there’s a good chance that you already write down a lot of your requirements on index cards. In that post, I outline a method that I’ve had a lot of success with in my own projects.

I went into a lot more detail in that post, but here’s a quick recap. First, I write the requirement itself on the front of an index card:

Nonfunctional requirement index card (front)

and on the back I’ll write a specific test to make sure the requirement is implemented:

nf_index_card_back.jpg

Then I use it for planning the project to make sure it actually gets included — you can see more about it in the post. As far as documenting nonfunctional requirements goes, that’s actually a really efficient way of doing it, and I’ve seen it work well on agile projects.

I hope that answers some of your questions about using nonfunctional requirements in software projects. Obviously, I’d be thrilled if you took a look at the requirements chapter in Applied Software Project Management — Jenny and I gave a lot of practical advice about how to use requirements on a software project. And I’ve got other requirements posts on Building Better Software as well. But if they don’t answer your questions, feel free to ask (or send them to us).

Using nonfunctional requirements to build better software

~ Andrew Stellman ~ 2 Comments

Understanding nonfunctional requirements — which some people call software quality attributes or nonbehavioral requirements — can make a big difference when you’re building software. But a lot of people have trouble taking a somewhat theoretical idea and applying it to a real-life project. Luckily, we’ve got an easy, practical technique to use nonfunctional requirements on a real software project.

Jeez, lady

How well does your program do… well, whatever it does?

I’ve wanted to write a post about nonfunctional requirements for a while. But I’ve been trying to find a good angle for talking about them, because while they can be really practical and useful on a software project, it’s a little hard to get that practicality across in a useful way.

Luckily, I’ve been spending a lot of time lately talking about architecture, since Jenny and I are going to give our Beautiful Teams talk at the ITARC New York conference next week. And that’s got me thinking a lot about how architects work. I’ve been asked more than once recently about what, exactly, the term “architecture” refers to. The quick answer is the textbook definition — designing, documenting and verifying the structure, components and properties of a system. But I always want to go beyond that. Any time I come across an interesting idea (and software architecture is full of them!), I try to come up with a way that it can help a developer out today, on a project that developer is working on. In fact, I’ve got a quick technique to help you do exactly that — it’s at the end of this post. And like many great software practices, it involves index cards.

So I started thinking about some common problems that software architects run into, especially junior ones who are still building up their experience. And that leads me straight to a problem that I’ve seen over and over again. A lot of people jump into architecture and design by starting with the question, “What’s this system going to do?” We’ve got a lot of very useful tools for that (like user stories and use cases). Obviously, you can’t design a system well without understanding what it does.

But I’ve had the opportunity to work with some very talented, very experienced software architects lately, and I’ve noticed something critically different about how they approach designing a system, and it’s really pointed me to an important difference that separates a senior architect from a junior one. When one of these guys gets started on a system, they don’t just think about what it’s going to do. They also think about how it’s going to do whatever it does.

That’s a really subtle point, and it’s a very easy one to overlook. But it’s very important. Important enough, in fact, to have a name: nonfunctional requirements.

Most of us have read about nonfunctional requirements. In fact, it’s a pretty common interview question: “Name a few nonfunctional requirements.” Someone who took a class in software architecture recently might be able to rattle a few of them off (usability, reliability, performance, scalability, availability…). And lots of project managers and business analysts I talk seem to be on an eternal quest for the perfect nonfunctional requirements template.

If you’re not familiar with nonfunctional requirements, here’s how Jenny and I defined them in our first book:

Users have implicit expectations about how well the software will work. These characteristics include how easy the software is to use, how quickly it executes, how reliable it is, and how well it behaves when unexpected conditions arise. The nonfunctional requirements define these aspects about the system. (The nonfunctional requirements are sometimes referred to as “nonbehavioral requirements” or “software quality attributes.”)

– Andrew Stellman & Jennifer Greene, Applied Software Project Management, chapter 6 (O’Reilly 2005)

And that’s a good starting point. But there’s an art to actually using nonfunctional requirements to make your software better. So how do we do that?

Thinking “how well” from the start

One of those senior architects I mentioned gave me a really good tip recently, one that really rings true. He told me, “Always think about performance from day one of your project, and test for it until you deliver.” Now, this particular person works on software tools used to design high-availability, high-performance server systems, so he thinks about performance a lot. But his point was that to design systems well, you need to think about performance — and other nonfunctional requirements — from the start.

Take a minute and think about that, because I think it’s an important point. I like it a lot for two reasons.

I like the fact that he’s thinking about how well the software works from the beginning of the project. I’m a firm believer in the old QA saying that “you can’t test quality in.” Yes, I know that saying rubs some people the wrong way because they think it sometimes lets people off the hook for testing at the end of the project. But there’s definitely a lot of truth in the idea that developers who think about quality from the beginning of the project build better software. If you design for performance, and if you then code for performance, then it’s pretty likely that you’ll end up with a more performant design than if only start thinking about performance at the very end of the project.

The other thing I like is that he didn’t say, “Think about performance, scalability, usability, robustness, etc., from the beginning of the project.” He narrowed it down to the single quality attribute that was most important to his particular project. I’ve talked to a lot of developers, project managers, designers, testers and business analysts over the years about nunfunctional requirements, and what I often find is that people seem overwhelmed. There are so many facets to quality beyond what the software does, and if you’re just trying to get started thinking about these things, it’s hard to know where to start.

Which leads me to my advice for developers. If you’re a programmer working on a project, here’s something that you can do today to improve the final product. Start with just three areas: availability, performance and reliability. I like these three because they’re easy to understand, it’s not hard to brainstorm examples of how they can go wrong.

Start with some definitions. Here are ones that Jenny and I gave in Applied Software Project Management:

Performance: The performance constraints specify the timing characteristics of the software. Certain tasks or features are more time-sensitive than others; the nonfunctional requirements should identify those software functions that have constraints on their performance.

Flexibility: If the organization intends to increase or extend the functionality of the software after it is deployed, that should be planned from the beginning; it influences choices made during the design, development, testing, and deployment of the system.

Reliability: Reliability specifies the capability of the software to maintain its performance over time. Unreliable software fails frequently, and certain tasks are more sensitive to failure (for example, because they cannot be restarted, or because they must be run at a certain time).

Now, make them practical and useful to your project by doing thee simple steps. To do this, you’ll need three index cards. Here’s what to do:

  1. On the front of each of the three index cards, write one a type of nonfunctional requirement at the top. So on the first card, write “Performance”. On the second one, write “Flexibility”. And on the third one, write “Reliability”. Write these words on the front and the back of the card. If bright colors grab your attention, use a bright-colored highlighter to highlight them. (Personally, they don’t really do anything for me.)
  2. Take each of the cards. On each of them write down the name of one feature f your software and what this particular attribute means for that feature. I like to use Search and Replace as an example whenever I talk about this sort of thing, because we’ve all used it and understand it. So on the Performance card I might write, “Search and replace: searching through a large document needs to be fast.”
    • Performance index card
  3. Here’s the hard part. On the back of each card, write down a single test that you can do to figure out how well your software meets that requirement. So on the back of the performance card I might write, “Replacing 100 occurrences of a 4-character string in a 25MB document has to take under 750 milliseconds.” (The more concrete you can make this test, the better this works.)
    • Performance index card (back)

Now that you’ve got those three cards, tack them up on your cubicle wall (or, even better, on your task board). Make sure the feature you wrote down in step #2 is facing forward. Make sure they’re someplace you’ll see them. Take just a minute or two each day to look at them and figure out if you’re headed in the right direction. What you’ll find more often than not is that as you’re designing your system, you won’t forget about those three things. Just spending a small amount of time writing down and thinking about these things can color your whole project.

Once you’ve moved from the design phase into the programming phase, flip the cards around so the test side is showing forward. (If you’re on an agile project with a three-week iteration, this might happen during the first week, but this works equally well for projects with a longer design phase.) As you’re writing the code for each of the features you wrote down, run that test by hand. It should only take a few minutes to do, and it will give you an idea of how well you’re doing. If you do this enough, you might end up figuring out a way to automate that test. If you do, and if you have a build server, then you can add it to the build. That way you’ll know any time you check in code that causes your project to see its performance (or reliability, or flexibility) degrade.

Try doing that on your next project, and what you should find is that you spend more time thinking about these things. When opportunities to improve those three specific things come up, you’ll recognize them and take them. And that’s a great way to build better software.

Requirements 101: User Stories vs. Use Cases

~ Andrew Stellman ~ 23 Comments

Business Analyst

Here’s a question that I get over and over again:

What’s the difference between user stories and use cases?

— Ron K.

Before I dive into an answer to that question, let’s rewind a little bit and talk about where user stories came from. I like them because they’re a great example of how the Agile movement changed the software world. Programmers used to just dive right into software projects and start coding. Whenever one of those pesky users started to tell us what they needed, we’d stop them and say something like, “Don’t worry, I totally get it. I know what you need.” The Agile folks figured out that “I know what you need” is a nasty little trap that programmers — especially good ones — fall into. We’d spend the whole project thinking that we understood our users’ needs, only to deliver software that they didn’t want. The Agile folks realized that if developers had to start working with users throughout the project to understand their needs if they wanted to avoid the code-and-fix trap.

Jenny and I teach you all about use cases and requirements in our first book, Applied Software Project Management (O'Reilly, 2005).

And that’s why I think the user story is one of the most useful tools to come out of the Agile movement. A user story — some people call it a scenario — expresses one very specific need that a user has. It’s usually written out as a couple of sentences. Most user stories are written in the language of the users, so any user should be able to read a user story and immediately understand what it means. A lot of time, user stories are written on index cards, although I’ve put them in Word documents, Excel spreadsheets and Wiki pages (depending on how the particular project is run).

A use case is similar to a user story, because it also describes one specific interaction between the user and the software. When I’m training people to improve the way they write down their project’s requirements, I often describe the use case as a “deceptively simple tool” that helps us find and write down all of the ways users interact with the software.

Looking at those definitions, I can definitely see why there’s confusion about the difference between user stories and use cases. If you look at the last two paragraphs, it might sound like I said the same thing twice! But while user stories and use cases are definitely similar, there are important differences between them. Each serves a distinct purpose, and I think they both have their place on a well-run software project.

I think the easiest way to understand the difference between use cases and user stories is to take a look at an example. Luckily, I’ve got one that I think helps make the difference clearer.

In our first book, Applied Software Project Management, Jenny and I spend a lot of time talking about how to develop use cases and use them to build better software. And as an example, we showed a use case for a software feature that everyone should be familiar with: a search and replace feature from a word processor. Comparing a user story for search and replace with a use case for the same feature helps highlight the differences.

It’s not hard to find lots of user story examples. There are lots of different ways you’ll see a user story formatted (although if you’re looking for a user story template, a 3×5 index card should be a good starting point!). So what would a user story for search and replace look like? I took a stab at writing one:

search-and-replace-user-story-card

(One thing I like to do with user stories is to use “he” or “she”, rather than try to be gender-neutral. I think this makes the user in the story easier to connect with by personifying him a bit. It it also lets me write in a more conversational tone, which makes the user story friendlier and, I think, a bit easier to read and understand.)

Now, if you’re not familiar with user stories, you might think to yourself, “Wait a minute, my word processor’s search and replace feature does a lot more than that!” And that’s okay. A typical user story will have enough information to help the user understand what it is the software needs to accomplish, but it’s not meant to be a complete description of how the software works. I’m not going to try to give a long lesson in writing effective user stories here; I highly recommend reading Mike Cohn’s excellent articles and posts aboout user stories. (Mike, incidentally, is one of the software development veterans who contributed to our latest book, Beautiful Teams [O’Reilly, 2009]. He has some really fascinating things to say about Agile planning.)

So what would a use case sample look like for search and replace? Here’s the use case example Jenny and I built to demonstrate how use cases work:

Name UC-8: Search and Replace
Summary All occurrences of a search term are replaced with replacement text.
Rationale While editing a document, many users find that there is text somewhere in the file being edited that needs to be replaced, but searching for it manually by looking through the entire document is time-consuming and ineffective. The search-and-replace function allows the user to find it automatically and replace it with specified text. Sometimes this term is repeated in many places and needs to be replaced. At other times, only the first occurrence should be replaced. The user may also wish to simply find the location of that text without replacing it.
Users All users
Preconditions A document is loaded and being edited.
Basic Course of Events
  1. The user indicates that the software is to perform a search-and-replace in the document.
  2. The software responds by requesting the search term and the replacement text.
  3. The user inputs the search term and replacement text and indicates that all occurrences are to be replaced.
  4. The software replaces all occurrences of the search term with the replacement text.
Alternative Paths
  1. In Step 3, the user indicates that only the first occurrence is to be replaced. In this case, the software finds the first occurrence of the search term in the document being edited and replaces it with the replacement text. The postcondition state is identical, except only the first occurrence is replaced, and the replacement text is highlighted.
  2. In Step 3, the user indicates that the software is only to search and not replace, and does not specify replacement text. In this case, the software highlights the first occurrence of the search term and the use case ends.
  3. The user may decide to abort the search-and-replace operation at any time during Steps 1, 2, or 3. In this case, the software returns to the precondition state.
Postconditions All occurrences of the search term have been replaced with the replacement text.

Now, if I were a developer building a word processor or text editor, I’d actually be able to write a search and replace feature that implements that particular use case. (Just to be clear: there are many different use case formats; Jenny and I use this use case template in our book because it’s stripped down to the bare minimum sections that we think an effective use case should have.)

Here’s something about use cases that I think is interesting. While you were reading through our use case example, were you thinking of something that looks like the Replace dialog in Notepad or Microsoft Word, or the Find dialog in TextEdit? If so, take another look at the sample use case. It doesn’t have any words like “window,” “button,” “click,” “field” or “checkbox”. It’s all about what actions the user takes, and how the software responds. And there are many different ways that you could build software that implements the use case. Have you ever used the search and replace feature in vi? What about the search and replace feature in Emacs? They have very different user interfaces! Who knew there were so many ways you could implement search and replace? But if you compare each of them with this use case, they all follow the same basic course of events.

So now that we’ve gone through the use case and user story examples, what’s the difference between user stories and use cases? Here’s what I think are some of the key differences:

  • User stories are about needs. When you write a user story, what you’re describing is a “raw” user need. It’s something that the user needs to do in his day-to-day job. If you never build any software for him, then that need will still exist!
  • Use cases are about the behavior you’ll build into the software to meet those needs. A developer who needs to build working software should be able to read a use case and get a good sense of what the software needs to do. It typically has a lot of detail, and describes everything that the developer needs to build in order to meet the user’s need. That’s why it needs to have a lot more detail, and be clear and unambiguous.
  • User stories are easy for users to read. When you write a user story, what you’re concentrating on is writing something that anyone can understand, in the language of the users. We all know that developers have a lot more patience for talking about details of the software they’re building than users do, which is why user stories have to be brief. A user story needs to express a complete thought in just a couple of sentences. (That’s also why it’s good to put them on index cards: somehow, that makes it clearer that it’s self-contained and independent of the other user stories.)
  • Use cases describe a complete interaction between the software and users (and possibly other systems). When you’re doing use case analysis, what you’re doing is designing a functional solution that meets the users’ needs. It needs to be something that developers can implement. It’s possible that one user story could spawn several use cases. And when you combine all of your use cases into one use case document, you’ll end up with a complete description of every interaction between the user and the software that you’re planning on building. And if your software has to interact with multiple systems, you may end up treating those other systems as actors in your use case.

Once you get a sense of how user stories and use cases differ, you can start to see what purpose they can serve on your project. And if you only use user stories, or if you only use cases, then maybe on your next project you can try using them both.