Exampler.comDriving Software Projects with Examples
Consulting, training, and writing from Brian Marick

Driving Projects with Examples: A Handbook for Agile Projects

This is a DRAFT chapter
Sun Sep 12 16:29:57 CDT 2004
Other chapters


I've written this book for two sorts of people. The first are people who don't want to be disappointed by the software they pay to have made. I'm going to call those people product owners. The second set are those paid to make software. Most are programmers, but there are some testers and project managers in the mix too. The second set doesn't want the first set to be disappointed, because the first set might stop paying them.

For the product owners, avoiding disappointment requires control. For decades, product owners have been told that control comes with knowing their own mind, expressing themselves exactly and completely at the beginning of the project, and otherwise keeping out of the way. That's silly. Think of pretty much anything important you do: driving a car, raising children, choosing a career. Would you really want to stake everything on getting those right up front?

This book is about another sort of control, the kind the product owner exercises through frequent conversations that are structured around examples. Those conversations give the product owner the ability to adjust as she learns, which enables her to have the team she's paying create a product that's the best she could get, knowing what she knows, in the environment she's in, with the team she has.

Each such conversation starts something like this:

Product owner: All months count as having thirty days.

Product maker: For example...?

Product owner: So, suppose that you buy a bond on the first of February and sell it on the first of March. Even though that's really 28 days (well, some years), you've owned the bond for 30 days.

Product maker: That's bizarre.

Product owner: It's just the way it works.

Product maker: Let's try a few more examples, see if I understand.

Thereafter, the programmer goes off and starts coding. Given sufficient examples, a well-motivated programmer with a few good practices under her belt will do a fine job of delivering what the product owner wants. And these conversations can continue throughout the project until the product owner has spent as much money as she cares to.

That's not to say that the conversations are simple; they're not. There are many forces to contend with, many tricks of the trade that lead to getting the right number - not too many, not too few - of the right sorts of examples at the right time.

And there's another complexity. Once the programmer and product owner have agreed on an example, the programmer has to convert the product from one that doesn't match it to one that does. (The example starts out as a bad example of how the product works; the programmer's job is to make it a good one.) That doesn't happen in an instant. Instead, the programmer will most likely move the product toward the example in small steps. Programmers are happier and more productive if they can ask, at each such instant, "Is the product getting better? Or have I messed something up?" They could answer the question by trying the product out manually, but that takes too much time. So instead, they want to answer the question by asking their computer to try out past examples to see if they still work. (Are they still good examples of how today's software works? Or has some change inadvertently made them bad examples again?) Since computers are dumb, that means the examples have to be written in some language that both the computer and a non-technical product owner can understand.

That sounds like a hassle, but I see it as a positive benefit. In any project where there's close conversational contact between non-technical business people and programmers, you essentially have two subcultures coming together, each with its own languge. Those people have to negotiate a shared language, a kind of pidgin or creole that's used for their specialized joint project. Focusing conversation on the written artifacts makes that joint language more concrete, more uniform, and makes it come together faster. In happy cases, a team's language and shared experience becomes a powerful tool of thought. On the business side, it makes it easier to envision useful new features. On the programming side, it helps produce the kind of well-tailored program that programmers find easiest to extend.

It was with that happy case in mind that I chose "driving" for the title of the book. I'm not a car person: I pretty much point the car in the direction I want to go and just take care not to run into anything. But even I can tell the difference between the responsiveness of a cheap sedan and an expensive sports car. The latter tells you more about the road you're on and the car's relationship to that road. I've never felt "one with the car" in the way that some people talk about it, but when I flew sailplanes, I got inklings of that feeling as I was circling in a thermal, just above stall speed, exquisitely alert to all sorts of subtle cues. It did (almost) feel as if the plane and I were a single organism.

In the same way, a project that's really humming along isn't one in which the product owner merely points in a direction, adjusts the course, and expects the programmers to supply motive power toward the goal. It's one where the team jells as a single unit, working together. Those are the great teams to be on, and I'll be happy if this book enables more of them.

There's another reason for the driving metaphor. Few people would willingly buy a car without test driving it first, even if they've read scads of reviews in car magazines, read all the manufacturers specs, the owner's manual, the maintenance manual, etc. Why not? Because you learn something by getting your hands on the car that you don't learn by reading about it. Any language about something introduces a layer of abstraction, puts you at a remove from the real experience.

The same is true of software products. Everyone - programmers and product owner alike - will understand the product better once they try it out. They'll understand the places it doesn't work right (despite doing what the product owner wanted), and they'll suddenly realize opportunities for new features.

But just as a car person would learn more from a test drive than I would, an experienced explorer of software will learn more than a novice. So this book also talks about how to generate real-time, hands-on examples that complement the written ones.

At this point in the writing of the book, I was itching to give an example. So that's what I'll do in Chapter 1. But first, there are things I should not omit from this Preface.


The Structure of the Book

The book is in four parts.

The first part of the book presents the basic idea, the approach that I'd want to take on a new project. It begins with that introductory example. It's part of the story of an imaginary project, relatively unadorned with explanations of what's going on. That's in keeping with my belief that examples can stand on their own far more often than you might suppose.

But they needn't stand completely on their own. Judicious, tailored commentary helps. If I were in the same room as you, we could discuss the Introduction and quickly zero in on the topics most helpful to you. Alas, I'm not, so I've written Chapter 2, filled with commentary on Chapter 1's story.

That story, supplemented by the commentary, should give you the feel of an example-driven project. That ends the first part. The second part is about details. It begins with a discussion of creating the first examples, those that bring the team together and get the programmers coding. (They're not going to wait around for complete instructions.) Then I take a digression into a vital skill, that of explaining and listening. Product owners are forever amazed at the ways programmers misunderstand; programmers are forever amazed at what product owners think is too obvious to mention. People good at explaining and listening will have fewer such surprises. Their examples will be better and, consequently, their project will go faster.

Examples start out verbal. To be properly useful to programmers, they can't stay that way. The chapter on writing examples down discusses good formats for examples, tools that the team might use, and how the process can be made smooth.

Each example causes exactly one particular use of the product. But a product has to be generally useful - it has to correctly handle an essentially infinite number of uses, under many conditions, by many people with many goals. The suite of examples presented to the programmers has to provoke the programmers to write the right program. It must contain examples with enough breadth to sample the important cases. Techniques to achieve breadth are mostly adapted from the world of after-the-fact product testing.

Since most of a programmer's time is spent coding up examples, the next chapter discusses various tricks of the trade. Here I talk about the importance of removing duplication, the way you can extract the domain model from the examples, and the interaction between business-facing examples and the more detailed ones programmers implement with tools like jUnit or nUnit.

Hands-on exploration is an important part of the project's overall iterative cycle. In the next chapter, I discuss how techniques of exploratory testing can be used in an end-of-iteration ritual that finds bugs, discovers interesting information, and uncovers ideas for later iterations.

At this point in the book, testing techniques and ideas have appeared, often in mutated form, but there's been no concentrated discussion. Now it's time to talk in detail about how testing fits in. Testing fills in gaps and acts as a safety net. There are some tasks for which examples are ill-suited, such as specifying security, so you'll need specialized testing as a backup. Less specialized testers can serve a valuable role as team members who do many jobs but have a particular emphasis on translating between product owners and programmers, ensuring that examples have enough breadth, and guiding exploration.

That discussion of testing finishes Part 2's description of the kind of project I'd love to work on. Part 3 describes variations: other people's ideal projects (maybe yours, too), and variations that work when you can't attain your ideal. These variations are based largely on the experience of different projects I've spoken to, visited, or worked with.

But we're not done yet. Every solution brings with it new problems, new challenges. So any purveyor of process should answer the question "what could go wrong?" That's what Part 4 is about: a handbook of what could go wrong. There are chapters on problems getting started, ruts people get stuck in, example 'smells' and whatever other clusterings come up when I generate and work through the whole list.



I thank you for reading. Please send me comments, questions, and suggestions.

Copyright (©) 2004 by Brian Marick. Permission granted to copy for personal use only. If you quote this, please identify it as a draft.

Comments to marick@exampler.com