Tuesday, November 30, 2010

The Woodchuck Factor

We've been writing our test plan for the next release, and the first draft contained a sentence that might as well have said:

Run the following tests:
  • Identify how much would a woodchuck chuck if a woodchuck could chuck wood, varying the amount of wood and the chuck factor.
  • Confirm that a woodchuck would chuck as much wood as a woodchuck could chuck, if a woodchuck could chuck wood.

Score one for incomprehensible sentences. The actual phrasing was of course, different, but it was the same effect: completely accurate and a good test, but expressed in a truly confusing way. We had hit the woodchuck factor.

The woodchuck factor is when a sentence in your documentation could be replaced with the woodchuck sentence and make about as much sense. (This is one of those things where we know it when we see it.)

Now first of all, these are the sentences that make me laugh, so that's a reason to look for woodchucks. But there's an actual problem here, too. It's really hard to understand, and it's fairly simple to misinterpret or simply skip because, well, that "doesn't make any sense" at first read.

If you hit the woodchuck factor, look for two underlying causes:
  • Overloaded Vocabulary. Are you using the same word as a noun and as a verb? Are you using the same word to describe multiple different things? Often we get away with describing two things with very similar terms, until we try to use them together - and then there's a woodchuck.
  • "Fancy" Phrasing. Woodchuck factors show up when you're trying to be "formal" or "fancy". Legal documents are notorious for this - "the party of the first part shall hereinafter be referred to as the First Part Party" - but it can happen to any of us. You can use formal language and still be declarative. Start with an example and generalize from there, but keep it simple.
Woodchucks are fixable. So the next time you find yourself reading a document and saying in your head, "How much wood would a woodchuck chuck...", laugh. Then fix it. Future readers will thank you.

1 comment: