Truth or Clarity?

13 Feb, 2008

Behind the scenes of The Art of Agile Development's Is XP Right For Us? sub-chapter.

There's this odd balancing act when you write... or at least, when I write. I find myself having to balance truth and clarity. Sometimes, absolute truth isn't very clear. Sometimes, clarity isn't totally truthful. I have to compromise on being factually correct in order to achieve my real goal: helping the reader.

Let's say that I was writing a "how to" book for the stock market. If I wanted to be totally truthful, I would say, "buy low, sell high." But that's not very helpful, is it? It's a platitude. Readers need more.

On the other end of the spectrum, I could be very helpful by saying, "Buy 300 shares of WidgetCorp and sell them in exactly three weeks." That's helpful advice! It's clear, concrete, unambiguous. Minor problem, though: it probably wouldn't work. Clear, but not truthful enough. Bummer.

This is the choice Shane and I faced as we wrote The Art of Agile Development. Truth? Or clarity?

Well, we wanted to write an especially hard-headed, practical book. We felt that agile development was "crossing the chasm"--that the audience for agile books was changing from early adopters, who were primarily interested in experimenting with the latest and greatest, to the early majority, who are primarily interested in ideas that help them do their job better. That meant we had to be very direct. Clear; pragmatic; hands-on. That was our goal. We chose clarity.

Okay, what happened to the truth? Well... I'll admit it. We lied. Sort of.

When providing a how-to guide, as we are, you generally have to pick one way of doing things. You can contrast various approaches, but that limits how much you can say about any one of them. In our case, we wanted to go into a lot of detail--334 pages of detail, in fact. Imagine what the book would have been like if we had tried to cover all of the other ways of doing agile development, too.

Although we had to pick one way, it couldn't possibly work for everyone. That's what makes the term "best practice" such a cruel deception. How can any practice truly be "best" in all situations, for all people? Best for who?

So we ended up writing a book that was, at its core, not entirely truthful. When we tell you that you should pair program and have everybody sit together, we could be lying. It's really only true if you're all in the same location, have a nice open workspace, and everyone involved has agreed to do so. We tell you that you can eliminate requirements documentation; it's only true if you have an on-site customer and are performing certain other XP practices.

That's what this section--"Is XP Right For Us?"--is all about. We're crossing our fingers behind our backs. We're providing context--describing what needs to be in place for our advice to work.

(Then, just because we know people won't read everything we wrote (gasp!), we repeat all of the important assumptions in the "Contraindications" portion of each practice.)

Truth? Or clarity? We chose clarity, and then fudged it by telling you how we were lying. I think all authors have to make this trade-off. Too often, the lies remain hidden, and you end up with "best practices." By making our assumptions visible, we risk scaring off some readers... but I think that, by doing so, we make our advice a lot more valuable, and a lot more likely to succeed.