When you read Christopher Alexander’s ??A Pattern Language, the patterns within the language are interdependent and ordered from big patterns down to small ones. Each pattern has a number and wherever one pattern refers to another it’s referenced with both the pattern’s name and its number.

Beck, Fowler and the Gang of Four (if memory serves) go one better, wherever they reference a pattern, they give the pattern’s page number (ah, the joys of computer typesetting). I’m not sure it’s an enormous improvement over pattern numbers with the pattern numbers in the running heads, but both practices make the books easy to use.

Writing this up as mini patterns, (very roughly based on Alexander’s pattern format) you’d have something like:

A Tiny Pattern Language for technical writers

1. Organizing Principle

You’re writing a ??Pattern Language on paper

Without some organizing principle, a random collection of patterns is just that

When you’re organizing material in a book which needs to be usable both as a learning resource and as reference material there’s a tension between the needs of the new reader who wants each pattern to follow logically from the patterns she has already read about, and the needs of a seasoned pattern user who needs to find details of a specific pattern.

It’s tempting to take the view that a reader is only new once, so it’s best to arrange the material to suit the reference user and put your patterns in alphabetical order. Don’t. If your material doesn’t make sense to the new reader, they’ll never reach the point where they use your book as a reference.

Therefore:

Arrange your patterns for new readers. Provide an index and cross references to support reference use

Use Arrange Patterns by Scale(2) to order your patterns and Reference by Name and Number(3) for your cross references. Provide a Table of Contents and an Alphabetical Index.

2. Arrange Patterns by Scale

You’re choosing an Organizing Principle(1) for your pattern language

It’s hard to understand a pattern without some idea of where it fits in the scheme of things

Read A Pattern Language, look at the way that each pattern in the book flows from the ones that precede it and leads you on to the patterns that support it. There’s a huge amount of information in that book, but it just flows. It has The Quality Without A Name.

Now read Universal Principles of Design, another book which contains a great deal of good information backed up with great pictures and some real research. Each spread in the book is analogous to a Design Pattern, and each spread is great. It’s a bugger to read though. The designers have chosen to arrange their principles in alphabetical order; reading through is like being taken on a drunkard’s walk by a conceptual grasshopper. Many of the principles are hierarchical, but the reader is left to work that out for themselves. It reminds me of the joke about reading a dictionary; the content’s great, but the characterisation and plot are all over the place.

Therefore:

Find patterns that use other patterns, put them before the patterns they use. Group patterns with a similar scale or motivation in chapters.

3. Reference by name and page number

You’re referring to a pattern.

Why can’t books be more like the web?

We’ve all done it I’m sure; one part of a book refers to another part and gives just the section title. We curse the author or his editor and go scurrying off to the table of contents or the index to find the referenced page and then turn to it, all the while keeping our index finger jammed between the pages so we don’t lose our original place.

Or the author has taken pity on us and, following the Chicago manual of style, supplies a section number (with multiple decimal points) and we start flipping forwards or backwards to find the right section number. This is less fun than it could be because no two sections are the same length. Or the content’s arranged alphabetically, and every section is the same length, but we’re not entirely sure of how many sections start with any given letter - I’m looking at you Universal Principles of Design.

There has to be a better way. Wouldn’t it be great if we could just go directly to the right page as if we were following a hypertext link?

Indeed it would.

Therefore:

Whenever you refer to another pattern, use both the pattern’s name and its page number; that way the reader can turn directly to the right page without having to visit an index or flip hopefully trying to guess how long each section is.

What next?

Obviously we need to hunt down and deliver a good telling off to authors, editors and publishing houses that don’t follow this pattern language.

Would you believe that I started this article meaning to write a review of Universal Principles of Design? Despite my grumbles about it above, it’s a cracking book full of really meaty stuff. I commend it to you all.