Structured writing, structured documentation
What’s it all about?
Modularized user documentation is today a virtual standard in professional technical publishing. If you look at, for example, a well-crafted Microsoft application user guide or online help file, you will see small, functional, repeated structures: a user procedure is always formatted the same way; a functional overview is always formatted the same way.
Why is this so? It is because throughout the first decades of the so-called personal computer revolution, leading software vendors (IBM, Microsoft, Xerox, Apple) invested millions in researching and developing effective writing techniques for their user assistance material. They all found that users learn faster and are more confident and productive when given cohesive, predictable, functional “chunks” of information with a clear structure. When standard information types are immediately recognizable and readily accessible (as they are wherever structured writing techniques have been applied), the software just seems to “work” better. So do its users. Everybody wins.
So what about structured writing and structured documentation: are they really the same thing? Not really, though there are areas where they overlap. Let's see if we can shed some light on the similarities and differences.
The term structured documentation comes to us from software engineering; it is an adaptation of the term structured analysis. It denotes the concept that computer documentation, like computer software, should be rigorously planned and designed before it is created. It proposes that documentation development should be approached in ordered phases, including requirements definition, design, writing, and testing.
The techniques of structured writing, on the other hand, grew out of research in the fields of educational psychology, instructional design, learning theory, and other academic disciplines. Its proponents believe that by understanding how readers process information, writers can create more effective documents.
So, to simplify things, we may think of structured documentation as a way of planning and implementing the various phases of a writing project; and we may think of structured writing as a set of tools and techniques to be used by writers during the writing phase of a project.
Invented in the late 1960s, structured writing began with three basic ideas:
-
There should always be a thesis statement at the top of the page.
-
Text should be presented in a two-column format to ease the task of skimming and scanning—one column for headings and one for text, with horizontal rules or white space separating each text block from the next.
-
The discipline of modularization ( “chunking” ) should be applied rigorously.
We’ve said that the concept of structured documentation proposes that documentation development should be approached in ordered phases. In his book How to Write a Usable User Manual, Edmond Weiss defines structured documentation as a process of planning and analysis in which the writing itself is only a small part. He identifies the five phases of a structured approach to user documentation:
-
Analysis Defining just what manuals and other information products the users and operators need.
-
Design Preparing detailed outlines of each manual or other information product.
-
Assembly Converting the storyboard to a work plan and writing the first draft.
-
Editing Testing the first draft for clarity, correctness, and readability.
-
Maintenance Keeping track of what needs to be changed in the information products and, when appropriate, making the changes.
Weiss characterizes a structured system as “a set of articulated modules” Likewise, a structured publication is also a set of articulated modules. Well-made modules are cohesive and predictable; they are functional, independent, and small. This is where the terms “structured documentation” and “structured writing” overlap. (You may already be using structured writing techniques without realizing it. One proprietary version of structured writing goes under the trademarked name of Information Mapping.)
Summing up, then, the difference between structured documentation and structured writing is mainly of scale and scope. Structured writing can be seen as a component of structured documentation. Or, working the other way, structured documentation can be seen as the logical extension of the principals of structured writing to all phases of an information design project.