Software Development

Admitting that you have a problem

~ Andrew Stellman ~ 2 Comments

It’s not always easy to recognize when your project is in trouble. Yes, if your project crashes and burns and completely fails to deliver, it’s failed. But sometimes you don’t realize that you’ve  or you’ve built the wrong software and are about to make your users very unhappy. That’s why Jenny and I put together our Why Projects Fail talk [pdf] a few years ago: to help people recognize when their projects are starting to go off the rails, and learn a few simple techniques for fixing them. If you learn to recognize the signs of project problems, it’s easier to take action quickly and turn your project around:

Software projects are a lot like cheesy horror movies. After you’ve seen a few of them, you know that the first guy to leave the group is going to get an axe in his head. Projects are the same way. People keep making the same mistakes over and over, and it keeps getting their projects killed.

– Why Projects Fail presentation, slide 6

But what happens when your problems are bigger than just one project? What happens when you’ve got a team, a department, or a whole organization that runs into trouble repeatedly on projects?

When Jenny and I were doing research for our first book, Applied Software Project Management (O’Reilly, 2005), we talked to many different people on all kinds of teams. And when we did, we started to notice something funny. We specifically reached out to people who had bad experiences with requirements, project management, Agile development—really, any way of trying to do things better. We were surprised that we kept hearing the same things over and over again, and started to suspect that they were symptoms of deep-rooted project management problems… and teams that were resistant to changing them.

Taking the first step

A list of the most common excuses—excuses that we’ve heard dozens or even hundreds of times, over and over again, from many different teams—is a surprisingly powerful tool. There have been many times when I’ve been brought in to try to help a team improve the way they build software. I’d be in the middle of an explanation of, say, why Agile has worked well for me in the past, and someone would give me an excuse that’s almost exactly word-for-word right out of our book. It’s actually pretty uncanny: how were we able to predict exactly what he would say in advance? But there it is, written down and printed in black and white.

That was the inspiration for the chapter in our book called Understanding Change. In it, we outline the most common excuses for sticking with a poor way of building software and not adopting something better. If you’ve ever tried to help your software team adopt a new tool, technique, or practice, you’ll see some very familiar arguments there.

Here are the top excuses that we’ve heard from teams that can’t admit that they have a problem. They’re all straight out of Applied Software Project Management. Treat each of these excuses as a big red flag, and you can use this to your advantage. If you’ve ever watched an episode of Intervention, you probably know that the first step to fixing a serious issue is admitting that you have a problem. Do they sound familiar to you? Have you ever heard any of them before? If so, it’s time to take the first step.

But if you do take the step and admit that you have project problems, that’s good news! It means that there are plenty of time-tested, tried-and-true ways to help your team. (Of course, if you’re a regular reader of Building Better Software, you already know that!)

Each of the following excuses is excerpted from pages 206 through 213 of Applied Software Project Management (Stellman A and Greene J, O’Reilly 2005). You can read a lot more about each one (and what you can do when you hear them from your team) in that chapter.

We Already Build Software Well

Denial is a common response to change. You may have identified a glaring problem, but people around you fail to even recognize it (or simply refuse to acknowledge it). Many professional software engineers and managers have never experienced a project that did not have enormous delays and serious problems; it’s often assumed that this is just part of how software is built. After all, they usually delivered something—most projects were eventually completed, and the software they built is now being used. Sure, some projects seem to always be eternally 90% done (with 90% left to go), but most of them seem to get something onto the users’ desktops (although many patches and bug fixes needed to be rolled out afterward). Isn’t that good enough?

“Not Invented Here” Syndrome

“Not Invented Here” syndrome (NIH syndrome) is a name given to a common type of organizational culture where people intentionally avoid research or innovations that were not developed within the organization. When faced with a problem, the people in the organization will typically reject a solution that is known to have worked elsewhere in the industry, solely on the grounds that it did not originate from inside the organization. They opt instead to build their own solution, often at far greater cost.

It’s “Too Theoretical”

When an idea does not make intuitive sense, many people will dismiss it as a result of “academic research,” which could not possibly apply to the world they live in. For example, to someone without a project management or software  engineering background, it may not be immediately obvious that reviews reduce defects, or that it’s important to write a specification before building software. To him, these procedures are time-consuming, with no obvious benefit. They sound good in a book, but would never work in the organization. In other words, they are “too theoretical.”

It Just Adds More Bureaucracy

An especially damaging attitude in some organizations holds that programming is the only important activity in a software project. Project management tools and techniques are seen as distractions that drain energy and effort away from the programmers’ “real job” of writing code. Any project activity that takes place before the programmers begin writing code simply amounts to “spinning our wheels,” and the goal of all early project activities should be to get the programmers doing the “real work” as quickly as possible.

You Can’t Give Me More Work!

Most of the changes that a project manager makes will increase the workload of other people. Software engineers, managers, and stakeholders who were not directly involved in building software will suddenly find themselves expected to attend status and review meetings, participate in planning and estimation activities, work with someone creating a vision and scope document or eliciting requirements, or perform other tasks that were never expected of them before. If you are making these changes, then you are the person piling additional work onto someone’s already overflowing plate. Not surprisingly, there are people who will not be happy with this arrangement.

It’s Too Risky

The economist John Maynard Keynes once wrote, “Worldly wisdom teaches that it is better for the reputation to fail conventionally than to succeed unconventionally.“ Legendary investor Warren Buffett put it this way: “Lemmings as a class may be derided but never does an individual lemming get criticized.” In other words, any manager who backs a change puts his reputation on the line; if that manager does nothing, he will not be criticized for maintaining the status quo.


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.

“That estimate seems a little long.”

~ Jennifer Greene ~ Leave a comment

Ever spend time working up an accurate estimate with your team, and find that it gets rejected because it doesn’t match a magic number in somebody’s head? You did your homework; talked to the people who’ve done this kind of work before, compared your estimate to past projects, and made sure that your estimates are coming from the people who will actually do the work. But, your boss thinks the project should be done a few months earlier. He doesn’t doubt your work, the estimate just doesn’t feel right.

Estimate

Estimates have a tendency to be more accurate when they’re based on experience. Having actual data on your past projects is so important when you sit down to figure out how long it’s going to take you to do a new one. The best estimates come from people who really understand the work that’s going to get done. And practices for estimation that stay grounded in project experience are less likely to be wrong.

That’s why your project will probably be really late if you just cave in and start shaving off time arbitrarily. It might not be easy, but you need to explain the reasoning behind the estimates your team has come up with and set your boss’s expectations realistically. Too many projects are in a bad position before they ever really get started because a project manager doesn’t correct this kind of misunderstanding.

It’s one of the toughest parts of the job because your boss doesn’t want to know all the details. He just wants you to get it done faster. And sometimes you can get done faster with more resources or with a different scope of work. But it’s always a mistake to just cut an estimate because it doesn’t match what people expect. You need to turn the conversation around and help everybody get to see what the real choices are. Just saying that project will take less time, never makes it happen that way– no matter how influential the person who wants it done yesterday is.

If you estimate right, you should never go back to your team and tell them to arbitrarily cut those estimates down. Instead, you should work with your boss to understand if there might be some work that can be cut from schedule, or some other ways to accomplish what needs to be done in parallel. If you set up a relationship where you and your boss are both doing everything you can to come up with a reasonable plan together, you stand a much better chance of succeeding.