JoAnn Hackos, PhD
With the burgeoning interest in content management, information developers need to think about embracing consistency as a strategic goal. If you want to mix topics written by many of your writers in the same deliverables, they need to be written consistently. We certainly don’t want our readers to think they’ve switched from Chaucer to Stephen King from one page to the next.
With the need for consistency foremost in everyone’s mind, you are prepared to move into the realm of structured writing. To pursue structured writing requires that we do much more than preach consistency. It means that we develop a program and information model that ensures that all our writers use a standard approach. Structured writing requires that four necessary components be defined: style, format, structure, and content.
Beginning with Style
When many of us focus on the problem of consistency in technical documents, we usually begin with consistency of writing style. In fact, style is a key component of structure. We may define, in our department style guide, rules for such diverse stylistic components as
- spelling conventions
- grammar and punctuation
- ordered and unordered lists
- passive and active voice
For example, your style guide may dictate that headings for task or procedure topics must begin with gerunds. A properly written procedure heading might read, “Turning on the power,” rather than “Power Initiation” or “Power Controls.” Or, your style guide may dictate that numbered or ordered lists be used only for action steps that must be performed in a particular sequence.
Consistency in writing style is essential for well-structured, reusable writing but it is not sufficient.
With desktop publishing (DTP) systems, format ordinarily is given equal or greater place than style in importance for maintaining consistency. Organizations hire or develop tools experts whose responsibility is to develop and maintain format standards for documentation. Typically, the formatting is handled in a desktop publishing tool, such as MS Word or Adobe FrameMaker, or in an output publishing system, such as RoboHelp or WebWorks. In some cases, final formatting is the responsibility of a production team, although most writers today work in WYSIWYG desktop publishing environments.
The format standard may not only specify that a heading 1 must be output in 16 point Helvetica Bold, but it may also specify that all chapters must begin with a heading 1 as the chapter title, all sections below the chapter level must begin with heading 2, and so on. We may even specify that chapter headings must appear in the header on the outside margin of every page of the chapter.
We can embed more specific format standards in our publishing tools by embedding rules that define the fonts to be used, their placement on the page, the spacing above and below, and so on. We can even assist writers in being consistent about their format by ensuring that a body text styled paragraph will always occur immediately following a heading or that two headings must be separated by a block of text.
Adding Semantic Structure
However, if we want to move from formatting to genuine semantic-based structure, we can move from a desktop publishing to an XML/SGML environment. In XML, not only can we specify a required sequence in the content units or XML elements, but we can also restrict the elements that can be used in a particular part of the text. For example, we can ensure that writers never include numbered lists in conceptual information by not making an ordered list tag available. Or, we can ensure that every action step begin with a command sentence such as “Turn on the power” before any additional information is provided.
Such structural rules tell the writer or the desktop publisher much about how the content units will appear in output but nothing about how they should be styled. A style guide sets the rules, stating, for example, that the command sentence in the action step always begin with a verb.
Unfortunately, neither writing style guides nor format rules embedded in DPT systems property sheets provide sufficient information for the degree of consistency required by structured writing and the promise of reuse. Structured writing requires more than following a style guide or using the correct formatting for a topic or a larger document.
It is also unfortunate that many consultants or vendors begin and end their information model exercise with the format rules. They often construct DTDs or schemas that mimic the property sheets in the original DTP systems, with the addition of rules that restrict the tags or elements available in particular contexts. Sometimes, the information models produced in this way do contain some guidance about structure. For example, a DTD may require that a paragraph stating the purpose of the task immediately follow the required task heading. Or, another embedded rule may require that warning or cautions must precede, not follow, an action step. But the information model that results still lacks a key component—how to address the information users’ needs.
More important, we need DTDs or schemas that provide guidance about genuine semantic-based structure rather than formatting. This guidance provides a basic level of assistance to writers during content creation. A common structure enables content to be more efficiently searched, retrieved, and reused.
Focusing on Content
Consistency in content is more important to the end user than consistency of style, format, or even structure. Consistency in content ensures that the end user can rely upon the information provided to answer questions, provide accurate and complete task instructions, supply the background information required for effective task performance, and so on. If we really want to provide users with consistent designed and written information resources, we must focus on content.
A few years ago, I worked with a new group of information architects responsible for creating a new information model for their organization. We analyzed the conceptual information that appeared in their documentation library—not an easy task. We had to sort out procedures and reference material to create a stack of content that was not either. What we had left contained definitions, process overviews, book and chapter overviews, introductions, and so on. The information that was supposed to help the users understand the products was neither complete nor coherent. One of the senior editors remarked that they really needed to get all the most senior writers together and decide what needed to be said about the product and write it.
This editor had hit upon the right idea to define the conceptual content. He wanted to discover what the users needed to know about the product to be successful in reaching their goals. Clearly, the starting point of a focus on content is a clear understanding of the users and their goals.
Usability experts advocate building user personas to define who and how people will use the functionality designed for a product. See Alan Cooper’s, The Inmates are Running the Asylum, for an explanation about the importance of personas and instructions for how to build them. Writers, too, need to define the user personas for their information if they are to determine how to develop usable and useful content.
Concepts, for example, should enable the users to gather the knowledge they need to reach their goals and perform tasks successfully as they use our products. All conceptual information must be in service of successful performance in our product world. However, to get the concepts right, the writers also need to know what knowledge the users already have about their goals, their tasks, and our products. We want to explain what is important but leave out what is already obvious. As every writer recognizes, making the choices between too much and too little is never easy. But without a well-defined set of user personas, based as much as possible on real-life users, the choice is impossible. In fact, users tell us that much of the conceptual information included in technical documentation is either trivial (inconsequential) or incomprehensible.
One way of defining content has been incorporated into the program for creating Reusable Learning Objects (RLOs) and Reusable Information Objects (RIOs) promulgated by Cisco Systems and based on the instructional design work of Ruth Clark and David Merrill. In her book, Developing Technical Training, Ruth Clark describes how one teaches a concept, using definitions, examples, and non-examples. Her prescription, based on instructional design, becomes the standard upon which Cisco and others create conceptual topics (RIOs) to be incorporated into course modules (RLOs).
Information developers, working together to define a sound information architecture, in preparation for content management and single sourcing, need to focus on content by defining quite precisely what kind of information their users need from procedures, concepts, and reference information. This content-based architecture should be incorporated into content guides that provide explanations and examples of just what a concept or a procedure should “feel” like.
The three-pronged approach described here is essential to effective and responsible single sourcing. It will result in a level of consistency in style, structure, and content that we see much too infrequently, and it will provide the level of flexibility in content design and development that we need to achieve the promise of component-based content management.
Just in case, here is a practical example of the distinctions I make among the four essential components: style, format, structure, and content
Consider the process of writing task-oriented headings:
Style: all task-oriented headings must begin with a gerund
Format: task headings are rendered in 16-point Arial bold, left justified, sentence case
Structure: all task topics must begin with a title
Content: all task topics must be immediately recognizable by the users as tasks they need to perform as part of their workflow
< title>Registering a new patient< /title>