General Criteria Protocol

• clear technical writing is preferred over academic diction
• consider length of pattern description carefully

(regarding writing style)

Absolutely. This is true for most submissions I received, however. Concrete patterns were submitted mainly by industrial people.

FrankBuschmann, June 1996.

• The paper should not over-theorise.
• The pattern should stand for itself i.e. several people should express that they have learned something from reading it e.g. "yes, I do that and it works" or "that's great, I can use that". Remember patterns are for sharing insight.
• Most theoretical discussions of patterns that I have seen (i.e. discussions that don't proceed by proposing specific improvements) require more experience with code (aka designs ...) to resolve, not more discussion.

A pattern doesn't work for me, as a piece of literature, if I can't understand it from reading a single page. A pattern should be a gestalt that fits into a few closely related neurons in my head; the content of those neurons should be a short, tight gestalt. I think one of the reasons we must pay close attention to writing style is to achieve the intensity and compactness to support this. Of course, there can be supporting material, examples, and references that go beyond a page; I really don't care how long that is. But the core must be short, or it can't be readily understood.

I think of the analogy to a design handbook. When I go to read how to use a specific transitor or op amp, I can quickly look at a table or description and learn what I need to know.

JimCoplien, June 1996.

Anyway, I'd like to argue that the ease of understanding of a document depends very strongly on the reader. I especially like the free-flowing style that Ward uses, and would have prefered that the Design Patterns book be more like that. However, I find that lots of people don't like it and find it hard to understand. I think it is too brief for them. The amount of description that you have to read depends on your background. If you've seen the pattern before then it only takes a little text to jog your memory and make you recognize it. If you haven't, it takes several concrete examples before you'll understand it. I also found that the catalog style of the GOF book is good for busy programmers who don't have time to read books because they can scan the patterns to get a general idea of what is in there and then can justify the time to read it in detail when they know that they really need it. This is completely different from my way of reading books, but I am an academic, and reading and writing is my business. Different styles will speak strongly to different people, and a style that you hate may be the best style in the world for someone else. This not only makes it hard to come up with a best style, it argues that there is benefit in people rewriting an existing pattern to fit it into a particular style.

RalphJohnson, June 1996.