Tips For Writing Pattern Languages

This is a message originally sent by WardCunningham to the PatternsList in January 1994. I can't find it archived online anywhere. SteveBerczuk sent me an OCR'ed version he had, which I just cut and pasted in. -- DougLea

Friends - I'd like to encourage all of you to get your pattern pencils out and get to work on your submissions to the PLoP'94 conference. To that end, let me suggest a few steps that have helped me get something down on paper. Also, I've included the introduction and section headings from what I expect to be my own submission: a pattern language I call CHECKS. But first the steps...

1) Pick a whole area, not just one idea. I like subject matter that is practical but seldom explored in a text book. You know, the kind of stuff you have to learn from your colleagues on the job. The discussion on the "patterns" list got me thinking about checking data.

2) Make a list of all the little things you have learned through the years about the area. Imagine that your kid brother has just taken responsibility for this area on his first big job. You're getting together this weekend. What are you going to tell him. Make a list.

3) Cast each item on your list as a solution. I like to write a sentence with "therefore" in the middle. You will have to think a little deeper here to figure out the forces that bear on your solutions. It's ok to speculate. I find this to be a rewarding activity since I often find new reason for what I do.

4a) Now write each item as a Pattern. I've come to favor a four paragraph form where the second paragraph ends with the pivotal "therefore:". This is a good time to flip through Alexander's Pattern Language. I feel my work has always improved when I more closely mimic his style. I'm just now learning to make the first and last paragraphs carry weight. These are the ones that link a pattern with others in the language.

4b) Organize your patterns into sections. Write a little introduction to each section that lists each pattern by name. You may find you need to adjust your linking paragraphs as you study the higher level structure of your patterns. Try to keep 4a and 4b fluid as you write. As you become more familiar with your patterns you may find that they organize themselves.

5) Now write an introduction to your pattern language that hints at the forces you will be addressing. Pick a good name too. And send a summary to the "patterns" mail list.

So, that's my formula. I think you'll find that even a sketchy pattern will stand better with other patterns around it. Now here is the promised summary of my CHECKS pattern language. This is offered for the immediate use of members of this list and should not be considered publication. Good luck with your writing. -- WardCunningham

Look for CHECKS at http://c2.com/ppr/checks.html.

See a recent companion piece, http://c2.com/doc/TipsForEditors.html.

Pattern languages describe an architectural school or style; have that school or style firmly in mind when working on each pattern and on the overall structure of the language.
Pattern languages are a DirectedAcyclicGraph (DAG) of patterns. There are many meaningful paths through the DAG. Don't focus on the paths through the DAG, but on the relationships between adjacent patterns - that leaves the designer free to choose a suitable path.
What are adjacent patterns? Each pattern's Context section should mention the patterns it presumes have been applied already as preconditions. Each pattern's ResultingContext? section should suggest patterns that may follow to balance unbalanced forces.
Individual patterns in a pattern language should encapsulate their own forces. That makes each pattern independent, so it can be applied independently of other patterns (without too much concern for the big picture at any given point). Good patterns should always be like this, but it's particularly important when the pattern is in a pattern language.
Try to make the patterns fit together in a way that no backtracking is necessary.
Use and reference existing patterns where possible, instead of writing your own.
Provide a good index; a graphical map of some kind is also very useful.
Not every collection of related patterns is a PatternLanguage; some are just a PatternSystem; some are just a PatternCatalog. Too often, things that are called patterns and pattern languages are just steps (rather than structure-preserving transformations) and recipes. Don't try to make it a pattern language unless it is one.
You won't get the patterns right, or the structure right, the first time, or the second time, and probably not the tenth time. Writing good pattern languages is hard - have patience, iterate, and seek input and feedback.
A pattern language is literature. Write it to entice someone to read it.

-- JimCoplien

Two comments on Cope's notes above:

(1) I'm not sure the graph of patterns in a pattern language is acyclic. It's certainly directed, though. For instance, many of my patterns reference other patterns that in turn reference the original pattern. In this way the reader is free, as Cope suggests, to choose his own path through the language.

: Right. Alexander's are all acyclic, and an acyclic graph is a desirable ideal. Software seems to need more iteration than houses do, so we maybe have more loops. On the other hand, I'm having a hard time coming up with examples. Do you have one? -- JimCoplien
: I found one: in writing PatternsForEffectiveUseCases?, we found that a use case is a completeSingleStory, each of whose individual steps might be a use case. There was therefore a recursive cycle from the step (forwardProgress) back up to completeSingleStory. At one point we had three such up-links, but found it terribly confusing. Essentially, there is only the one, so we dropped the other two. The reason was the recursion in the use case structure, which can be arbitrarily deep. Such an arbitrarily deep recursion doesn't occur in houses.

(2) Even though you shouldn't concentrate on the paths through the language you should probably make sure that there IS at least one path through the language. Remember that some people will take the linear approach to reading a pattern language. The linear read-it-from-cover-to-cover approach should at the very least be a valid path through the language.

Kyle, if that's true, how do you handle the case where one pattern suggests one of two alternative patterns as a follow-on? You can't do both. In general, the structure cannot be linearized. By breaking selective links in the DAG and doing a depth-first traversal, you come pretty close to an acceptable linearization. But if you get a perfect linearization, I'd bet it's a simple recipe, not a pattern language. -- JimCoplien

I think that the previous point about cycles helps in the linearization. Two alternatives can point back to each other - you read the first and then the second and then proceed. -- KyleBrown

I haven't undestand why Alexander's pattern language is described as acyclic. I've traced it (see on http://manyeyes.alphaworks.ibm.com/manyeyes/visualizations/cristopher-alexander-patterns-lang), it have lots of cycles -- MicheleMauri?

The best pattern language I've ever studied is the original language, composed during 8 long years by Christopher Alexander and his colleagues and called A Pattern Language. If you'd like to learn how to write great pattern languages, study the original pattern language. In it, you'll find great wisdom, communicated for laypersons using pictures, stories, quotes, sketches, and wonderfully written bold headlines. Consider how you feel after you read this book, and compare it with how you feel when you read other pattern languages. Do you get the same feeling? Or is something missing from those other languages? If you can discern what is missing, you are well on your way to understanding what makes great pattern language truly great. And then you'll be ready to write your own. -- JoshuaKerievsky

I just went through the process of making a presentation of the SoftSecurity PatternLanguage. In the midst of doing this, I realized I had to organize the patterns in a manner that my audience could progressively understand the ideas since the presentation is oral. Not only did this make the pattern language clearer for me, it also exposed new relationships between the patterns. Consequently, I've been linking the patterns/pages together on MeatballWiki more tightly than before as I write the presentation. I also have the empty feeling that there are many, many missing patterns and concepts. I also have noticed my failure to research the patterns thoroughly, relying primarily on my experiences with MeatballWiki, WikiWiki, and KuroShin, each of which I've had an influence in. This is a serious violation of Pattern authorship. -- SunirShah

CategoryGroupsOfPatterns