Startle And Shout

Posted January 30, 2000 by Joshua Kerievsky

"...to the hard of hearing you shout, and for the almost-blind you draw large and startling figures."—Flannery O'Connor, "The Fiction Writer and His Country"

Experts can walk into situations, see problems, and use their considerable experience and knowledge to begin solving those problems. Non-experts can't do this.

More than a decade ago, pioneers of the software Patterns movement set out to help non-experts leverage the knowledge and experience of experts. Their strategy was to write Patterns and Pattern Languages and to encourage others to do the same.

Suddenly, experts began to pour out their wisdom. They cast their words into unique Pattern forms. Books and articles were published. Conferences were conducted. A new literature emerged.

And now, over a decade later, the question is, has this helped?

I would say, in a queasy voice, sort of. Non-experts now have volumes packed with advice and wisdom, but they still lack an easy way to map their problems to this body of knowledge.

Without this capability, the great body of Patterns literature simply doesn't deliver.
But the problem is actually worse.

Many non-experts simply don't know what problems they have. Consider novice programmers who aren't aware of the problems that can arise from creating huge class hierarchies, writing bloated methods, or producing vast amounts of conditional logic or duplicated code. Without knowing that these are problems, how will these novices use the Patterns literature to help them?

But wait, aren't Patterns supposed to describe genuine problems and present real solutions to those problems? Yes, but the Patterns literature has failed to do this effectively.

Authors have written stale, dry, bullet lists of forces, and have asked lots of questions,
but have failed to sufficiently describe the ugly and awful situations that occur when no solution is in place.

For instance, in James O. Coplien's A Development Process Generative Pattern Language, there is a Pattern called SIZE THE ORGANIZATION, in which the problem is posed as this question:

Problem: How big should the organization be?

Now that question simply fails to grab the readers attention. Compare it to this revised version of the problem statement:

Large software projects (greater than 25,000 lines of code) are seldom delivered on time and within budget when the development team is either too large or too small.

Now that captures attention. It states specifically what happens when the solution isn't in place. And since delivering late and over-budget is clearly something we'd like to avoid, the reader is far less likely to skip over this Pattern.

Patterns authors could learn much from fiction authors like Flannery O'Connor,
who is considered by many to be one of the best short story writers of the 20th Century.
Patterns authors must draw large and startling figures of real-world software problems, and shout whenever necessary to make sure novices realize how bad problems can be.

That is not to say that Patterns authors must always use strong language and bold type. But in places, this kind of language is necessary, particularly in the problem statement, which must describe the ugly and awful situations that occur when no solution is in place.

When the compelling language of a problem statement jumps out at a reader and grabs his attention, the reader can suddenly identify the problem in his own work. Once that happens, the reader will be very interested in studying and understanding the Pattern's proposed solution.

Today's body of Patterns literature doesn't do a great job of describing problems. To improve this, authors must endeavor to

Describe the Problem
Clearly show the reader what a situation is like when the solution is not present.
Show, Don't Tell
For instance, instead of saying a carpet is old, describe the carpet's tatters and stains and dull color.
Let Images Do the Talking
Some people process information better visually, but everyone can benefit from an image or sketch that really exemplifies an idea.
Highlight the Headlines
If something is especially crucial, make sure it stands out.

As Patterns authors improve in their ability to communicate essential ideas, like the problem statement, the body of Patterns literature will become far more useful for the real end-user: the non-expert.