Our Articles ...

On Complex Documentation

On Personalizing Content

On Complex Documentation

 On Kids' Software

On Home Software

On TV and Video

On Art, Poetry, & Drama

What Technical Writers Can Learn from Christopher Alexander's Pattern Language

by Jonathan Price

Draft of Interface Feature for IEEE Transactions on Professional Communication

Publication Referred to: C. Alexander, S. Ishikawa, M. Silverstein, with M. Jacobson, I. Fiksdahl-King, S. Angel, A Pattern Language: Towns, Buildings, Constructions. New York: Oxford, 1977

Index Terms: Pattern, pattern language, object orientation, object-oriented rhetoric, styleguide, standards

In a series of books [1] - [5], Christopher Alexander, an urban planner and architect, has inspired object-oriented programmers with his idea of a pattern language-originally, a catalog of solutions to common problems faced by any community or individual creating a livable structure such as a town or a house. His approach might also help technical communicators polish and perfect our own standard rhetorical structures (such as the procedure, user guide, or reference), viewed as common ways of answering frequent, if virtual, questions from our users . Alexander's way of describing age-old patterns such as neighborhoods, streets, paths, and homes may give us a model for creating our own set of patterns in technical communication, whether or not we adopt some of the eager elaborations offered by folks in the object-oriented design world. What's a pattern? For Alexander, a pattern is a practical guide to resolving any problem that occurs over and over, such as how to lay out common ground for a town square, or punch a hole in a wall for a door. In A Pattern Language [4], he and his team have created each pattern out of the same elements:

• A picture of an archetypal example of the pattern. For example, to illustrate the pattern Small Public Square, Alexander shows a photograph of people playing, chatting, and strolling around a small plaza, shaded by trees. [4, p. 310]
• An explanation of the context in which you would use the pattern, often consisting of other, larger patterns it could fit into. The Small Public Square, for instance, fits into another, larger pattern known as Identifiable Neighborhood.
• A statement of the problem, with research outlining the basis for the problem, consideration of its validity, and, if necessary, an investigation of the range of different ways the problem may appear. For example, studies show that two people with normal vision can communicate comfortably up to 75 feet, so Alexander recommends that the Small Public Square be no wider than that, to ensure that the people feel as if they are really sharing the space with other people they can recognize and talk to.
• A solution, stated in the form of one or more instructions, "so that you know exactly what you need to do." [4, p. xi] For example, Alexander recommends a width of "no more than 45 to 60 feet across, never more than 70 feet across." [4, p. 313]
• A diagram with labels indicating its main components. For example, Alexander provides a rough sketch of the blocks making up a neighborhood, showing the Small Public Square in the middle. [4, p. 313]
• A list of lower-level patterns which might be needed to carry out this solution, complete it, or embellish it. For example, the Small Public Square might contain smaller patterns featuring stairs you can sit on, a focal point such as a bandstand, and areas where people like to congregate, such as street cafes, newsstands, bus stops, trellised walks, and promenades. [4, p. 314]

The methodicalness with which Alexander carries out this analysis seems to appeal to the orderly nature of many engineers, even when the subject matter is apparently outside of their discipline. In A Pattern Language [4] Alexander discusses 253 patterns in 1171 pages (an average of 4.6 pages per pattern). He organizes these patterns by scale, from largest to smallest, considering the distribution of towns before "activity nodes" within towns, which appear before any actual buildings, which in turn appear before parts of buildings, such as alcoves.

The sequence resembles what object-oriented programmers call a composition diagram, in that the larger patterns often require a dozen or more medium-level patterns as components, and those mid-level patterns themselves assume the lowest-level patterns as subcomponents. For example, Alexander loves the idea of a town green like the ones that grew out of common grazing areas in Europe and New England. In pattern 60 he adapts this idea, arguing for a little green within or around a small cluster of houses or workspaces, as a relaxing common space within three minutes walking time from anyone's door. He calls this pattern the "accessible green" [4, pp. 304-309] and argues that such a green will help define a neighborhood or work community, provide a tangible boundary between one group's area and another, and form a quiet backside to the houses that stand between it and a road. In turn, the green should contain pleasant outdoor spaces, plenty of trees, and, ideally, a wall against which people can plant a garden.

Here's how Alexander describes the componentization here:

The pattern helps to complete those larger patterns which are "above" it, and is itself completed by those smaller patterns which are "below" it. Thus, for example, you will find that the pattern ACCESSIBLE GREEN (60) is connected first to certain larger patterns: SUBCULTURE BOUNDARY (13), IDENTIFIABLE NEIGHBORHOOD (14), WORK COMMUNITY (41), and QUIET BACKS (59). These appear on its first page. And it is also connected to certain smaller patterns: POSITIVE OUTDOOR SPACE (107), TREE PLACES (171), and GARDEN WALL (173). These appear on its last page. What this means is that IDENTIFIABLE NEIGHBORHOOD, SUBCULTURE BOUNDARY, WORK COMMUNITY, and QUIET BACKS are incomplete unless they contain an ACCESSIBLE GREEN; and that an ACCESSIBLE GREEN is itself incomplete unless it contains POSITIVE OUTDOOR SPACE, TREE PLACES, and a GARDEN WALL [4, p. xii].

In object-oriented terms, each pattern has several component relationships with other patterns. As Alexander says,

Each pattern can exist in the world only to the extent that it is supported by other patterns: the larger patterns in which it is embedded, the patterns of the same size that surround it, and the smaller patterns which are embedded in it [4, p. xiii].

Such sensitivity to context grows out of Alexander's fundamental view of the world: It says that when you build a thing you cannot merely build that thing in isolation, but must also repair the world around it, and within it, so that the larger world at that one place becomes more coherent, and more whole; and the thing which you make takes its place in the web of nature, as you make it 94, p. xiii].

This spiritual quest for wholeness-at many levels-gives Alexander's writing a depth and resonance we rarely encounter in technical works. He sees his inspiration coming not from contemporary architects, urban planners, and landscape designers, but from the genius of hundreds of generations of ordinary people around the world-the folk who created roads, houses, town squares, and windows in the first place. He is looking for "a timeless way of building" [2] or at least one that has been sanded and polished by many generations of people reacting to common problems. He seeks the essence of their solutions, so that, as he puts it, each solution "contains only those essentials which cannot be avoided if you really want to solve the problem. In this sense, we have tried, in each solution, to capture the invariant property common to all places which succeed in solving the problem" [4, pp. xiii-xiv].

How do Patterns Form a Language?

Alexander offers these patterns to designers and non-designers alike as a language, by which he means a way of expressing one's self, in space. He argues that conventional architects have so denuded the landscape that most ordinary people have forgotten that they themselves can build perfectly attractive houses, neighborhoods, and work spaces-if they only had the "grammar" and "terms" to speak in that way. The languages which people have today are so brutal, and so fragmented, that most people no longer have any language to speak of at all-and what they do have is not based on human, or natural, considerations [4, p. xvi].

He sees himself as resurrecting patterns that are archetypal-"so deep, so deeply rooted in the nature of things that it seems likely that they will be a part of human nature and human action as much in five hundred years as they are today" [4, p. xvii]. He is speaking of architectural elements such as the arcade, but in his somewhat-Taoist, somewehat-Platonic approach, he holds out the possibility that if we use these patterns we will make our own spaces more livable.

And, as with any language, the most condensed expression has the most poetry. It is possible to make buildings by stringing together patterns, in a rather loose way. A building made like this is an assembly of patterns. It is not dense. It is not profound. But it is also possible to put patterns together in such a way that many, many patterns overlap in the same physical space: the building is very dense; it has many meanings captured in a small space; and through this density, it becomes profound [4, xli]. This hope for a quintessential solution and extreme compactness of delivery may also appeal to engineers such as object-oriented programmers, who see that they have been creating similar solutions over and over, but dream of seeing the one simplest and best solutions, for extremely efficient code.

How Object-Oriented Programmers have Evolved the Pattern Language

Alexander's work has dovetailed with many of the concerns of object-oriented programmers [6] - [24]. For instance, several of these programmers [6], [9], [11], [12], [16], [17], [19], [23], [24] were concerned with:

• The fact that they encounter similar problems over and over, and would like to be able to solve these problems with the same well-designed object, rather than inventing new objects each time
• Hence, the desire to reuse well-built objects
• The consequent need to communicate to each other in a consistent way about the objects they have already created, that might be reused

As Rising [22] says, "A pattern is, on the surface, simply another form of documentation." In this sense, any technical communicator who is documenting a program written in an object-oriented language such as C++ or Java will find Alexander's work an inspiration, and prototype. But for the programmers, patterns offered something much more than annotated code. As Rising [22] says, "The power of this kind of documentation is that knowledge previously found only in the heads of experienced developers is captured in an accepted form that can be shared." Patterns gave the field a way to mature, by creating handbooks of best practices. Patterns also share a number of characteristics with programming objects, according to Lea [19]:

• Encapsulation, because each pattern is independent, and makes sense as a stand-alone method
• Generativity, because each contains instructions on how to construct instances of this class
• Equilibrium, or a way of reaching harmony among contending forces
• Abstraction from the local and specific, to the more general within the context
• Openness, because the pattern may be extended to various levels of detail
• Composibility, because patterns are composed of other patterns, and so on.

And the process Alexander envisions people using to apply the patterns echoes many of the activities on an object-oriented team, according to Lea [19]: piecemeal development, frequent iteration, prototyping, collaborative development, participatory design, decentralized work that must eventually fit together in an integrated whole.

Patterns, then, caught the imagination of the object-oriented programming community because Alexander's approach offered a method for documenting successful objects, and, in turn, patterns resembled high-level objects, while the process of turning a pattern into a plaza or home also resembled some of the activities on an object-oriented team. Patterns have become a way of sharing ideas in this community, and although many engineers have developed much more elaborated models, with as many as a dozen or more elements, the approach began with Alexander, and for many technical communicators, Alexander's writing will seem more sympathetic, humane, and understandable than some of these no-nonsense, hard-hitting analyses of software patterns.

How Technical Communicators May Learn from Alexander

First, we can come to appreciate the value of a methodical analysis of each "solution" we use, whether large (a help system), medium (a language manual), or small (a quick start guide). Patterns are what we may have been groping toward in many of our styleguides, in which we offer tidbits of advice from managers and editors, with occasional examples of templates, and final output. Among the many problems with current styleguides [25], [26] is the fact that they are often inconsistent, including some analysis for some elements, but not for others, and focusing more on format than on purpose, with little or no discussion of context (higher level patterns this one forms a part of, or component patterns within it). Of course, writers are not as enamored of regular analysis as engineers are, but a more methodical consideration of the important elements in our documentation might provide advice that people could really follow, particularly if we were to add an Alexandrian analysis of the rhetorical context (what's the problem that this particular element solves? What user question are we answering here?). Thus, our styleguide would offer considerations of all the following for each element, regarded as a rhetorical object [27] - [30]:

• The larger context, or pattern, into which this element fits (specifically, larger objects of which this may be a component). For instance, the object we know as a Step fits into a larger object called a Procedure.
• The user's problem or question, which this element responds to (in object-oriented terms, its responsibility or function). The Step responds to the user's question, "What do I do now?" Therefore, a paragraph is not really a legitimate step if it attempts to answer a substantially different question, such as, "What's the result of the action I just took?" Focusing on the object's function helps us spot bogus, or pretend, steps quickly, speeding up our editing or revision.
• A standard name for the solution (the class name). The official class name for this object would be Step.
• Specific instructions for creating the solution. To create one instance of the class of Step, we might recommend that writers start with a number (except when a procedure contains only one step, which we might bullet), then a verb in the imperative (although at times we would OK someone starting with a little context), and a single instruction (not several).
• Component elements of the solution (each with its own pattern described elsewhere), with information about which ones are required, and how many, in what order. With a step, we might require that writers start with one number or bullet, allow as many glossary terms as necessary, and allow, as optional sub-components, in order, one or more explanations of the instruction, one or more descriptions of the results of carrying out the instruction, one screenshot (not more), and one or more examples. All of the explanatory elements would probably get their own formatting as separate paragraphs while being considered, logically, as subordinate objects within the Step object.
• Attributes of the element, such as creator, date of last modification, file format, subject matter. The Step, for instance, would probably inherit the values for the first three attributes from the super-object-the document as a whole-but might have a unique value for the attribute Subject, such as "Attaching propeller bolt," so users could search for procedures involving that bolt as part of the subject matter.
• Other objects that this one communicates with, as when a term requests its definition to appear in a pop-up window (essentially, targets of links). In some organizations, the Step is all the user sees, but the Step is hot, so if a user clicks it, explanations appear; in that situation, the Step is seen as communicating with a description of the results, a screenshot and an example, if any.
• Examples of the solution. With a Step, we might show examples of a step beginning with a verb, a step beginning with context, a step in a one-step procedure, and a step that branches into two substeps (yes, the substep might be considered another object, or it could just be seen as an allowable variation on the standard Step).
• Rhetorical advice about how to modify the object depending on shifts in the audiences addressed. With a step, for instance, we might point out that the concept of "a single meaningful action per step" must vary by audience. For an absolute beginner, one step might be a complex alphanumeric command to be typed, because that takes a lot of concentration, and another step might be pressing Enter, which can be a metaphysical challenge for someone who has never used DOS, whereas for an experienced user, a step would include both instructions, because the expert conceives of "entering the command" as a single meaningful action.

An Alexandrian approach also deepens our rationale for the standard elements in our documents, casting them not as arbitrary decisions made by some unseen editorial board, but as a response to certain types of questions raised by users over and over, not just in our own organization, but in others like it, for dozens of years. In other words, a patterns approach considers a procedure as a generic form developed by many teams interacting with thousands, even millions of users, over many, many years. The structure may vary slightly from place to place, under local circumstances. But the essence of the form, its formal structure, remains solid, the result of all that social polishing. Each pattern, then, describes an element-an illustration, a migration guide, a glossary item-as a rhetorical object, the writer's equivalent of a programming object. And whenever we begin using object-oriented databases to store our information, or work in languages like SGML or XML that allow us to tag the content as well as the format, then the pattern analysis provides us with clearly defined descriptions of each object, from a writer's point of view, while the tag itself tells the software what kind of object it is, in programming terms. The more information we must handle, it seems, the more likely we are to need patterns to help us create humane, aesthetically pleasing, and enduring information objects for our users.

References

[1] C. Alexander, Notes on the Synthesis of Form. Cambridge, MA: Harvard, 1964.

[2] C. Alexander, The Timeless Way of Building. New York: Oxford, 1979.

[3] C. Alexander, M. Silverstein, S. Angel, S. Ishikawa, D. Abrams, The Oregon Experiment. New York: Oxford, 1975.

[4] C. Alexander, S. Ishikawa, M. Silverstein, with M. Jacobson, I. Fiksdahl-King, S. Angel, A Pattern Language: Towns, Buildings, Constructions. New York: Oxford, 1977.

[5] C. Alexander, Ed., with H. Neis, A. Anninou, I. Fiksdahl-King, A New Theory of Urban Design. New York: Oxford, 1987.

[6] W. Brown, R. Malveau, H. McCormick, and T. Mowbray, Anti-Patterns: Refactoring Software, Architectures, and Projects in Crisis. New York: Wiley, 1998.

[7] D. de Champeaux, D. Lea, and P. Faure, Object-Oriented Systems Development. Reading, MA: Addison-Wesley, 1993.

[8] P. Coad, "Object-oriented patterns," Communications of the ACM, Vol. 35, No. 9, pp. 152-159, 1992.

[9] P. Coad, D. North, M. Mayfield, Object Models: Strategies, Patterns, and Applications, 2nd Edition. Englewood Cliffs, NJ: Prentice Hall, 1996.

[10] J. O. Coplien, Advanced C++: Programming Styles and Idioms. Reading, MA: Addison-Wesley, 1991.

[11] J. O. Coplien, Software Patterns. New York: SIGS Books, 1996.

[12] J. O. Coplien and D. C. Schmidt, Eds, Pattern Languages of Program Design. Reading, MA: Addison-Wesley, 1995.

[13] S. Dasgupta, Design Theory and Computer Science. Cambridge, UK: Cambridge University Press, 1991.

[14] M. Fowler, Analysis Patterns: Reusable Object Models. Reading, MA: Addison-Wesley, 1997.

[15] R. P. Gabriel, Patterns of Software. New York: Oxford, 1996.

[16] E. Gamma, R. Helm, R. Johnson, and J. Vlissides, Design Patterns: Elements of Reusable Object-Oriented Systems. Reading, MA: Addison-Wesley, 1995.

[17] A. Goldberg, and K. S. Rubin, Succeeding with Objects. Reading, MA: Addison-Wesley, 1995.

[18] IEEE Software Special Issue on Objects, Patterns, and Architecture, January, 1997.

[19] D. Lea, "Christopher Alexander: An introduction for object-oriented designers," Software Engineering Notes, ACM SIGSOFT, Vol. 19, No. 1, p. 39, 1994.

[20] L. Rising, The Patterns Handbook: Techniques, Strategies, and Applications. New York: Cambridge University Press, 1998.

[21] L. Rising, "The road, Christopher Alexander, and good software design," Object Magazine, Vol. 7, No. 1, pp. 46-50, 1997.

[22] L. Rising, "Design patterns: Elements of reusable architectures," in Annual Review of Communications, vol. 49. Chicago, IL: International Engineering Consortium, 1996, pp. 907-909.

[23] T. Love, "Timeless design of information systems," Object Magazine, November-December, p. 46, 1991.

[24] E. Yourdon, Object-Oriented Systems Design. Englewood Cliffs, NJ: Prentice Hall, 1994.

[25] D. W. Bush and C. P. Campbell, How to Edit Technical Documents. Phoenix, AZ: Oryx, 1995.

[26] J. A. Tarutz, Technical Editing: The Practical Guide for Editors and Writers. Reading, MA: Addison-Wesley, 1992.

[27] J. Price, "Structuring complex interactive documents," Introduction to a special issue (same title) of the IEEE Transactions on Professional Communication, July 1997, pp. 69-77.

[28] J. Price, "Using complexity theory to understand what's happening to technical Communication," in IPCC 97 Proceedings, October 22-25, 1997, Salt Lake City, Utah. IEEE Professional Communication Society, 1997, pp. 17-27.

[29] S. Mazumdar, W. Bao, Z. Yuan, and J. Price, "Adding semantics to SGML databases." Presentation at Electronic Publishing '98 Conference, Saint Malo, France (April 1-4, 1998), and to be included in the proceedings volume, 1376 in the Lecture Notes in Computer Science Series, Springer-Verlag, Berlin, 1999.

[30] J. Price, "Complexity theory as a way of understanding our role in the World-Wide Web," in Proceedings of the 45th Annual Conference. Arlington, VA: Society for Technical Communication,1998, pp. 207-209.