Once you take on a unified content strategy, authors will create content for a number of different purposes, but with greater integration and far less duplication of effort. An author may create a product description that will be used in a printed brochure, in a product catalog that forms part of the external web site, on an intranet that mirrors the external web site but provides additional details, in the user guide, and in training materials. In some cases, the same author may reuse the content that he or she creates, but other authors may also retrieve it and use it for their purposes. The whole idea behind reuse is to avoid “reinventing the wheel,” but for reuse to occur, authors must focus on the content’s meaning as opposed to its format. That is, they write it independent of where or how it may appear. This is a difficult concept for some authors to adopt, but separating content from format provides your organization with ultimate flexibility in how the content is used and displayed, both today and into the future. After all, even though you model the potential uses for your content, you never know when new uses may arise.
This chapter discusses why it’s a good idea to separate content from format and describes the structured writing principles that allow authors to focus primarily on content. It also challenges the belief that for content to be effective, authors must know exactly how it will be used. To that end, this chapter provides some guidelines for writing the same content so it works in different media and for different uses.
When implementing a unified content strategy, it’s critical that authors structure and write their content consistently. Well-structured content leads to more opportunities for reuse across product lines, audiences, and information products, as well as to greater return on investment. Not only can content be reused more effectively if it is structured consistently, it can also be used more effectively. Well-structured content is more usable content, potentially reducing support calls from customers and staff who need assistance finding or interpreting information.
In “traditional” environments, authors write the content, then format it to accommodate the media in which it is being delivered. Authors will often spend hours and hours adjusting such things as font size, kerning, paragraph and line spacing, as well as margins—anything to make the information fit its particular format. In addition to format changes, authors will often make content changes if they decide to use the same content elsewhere. They may change the focus of the content slightly (to make it more marketing-oriented, for example), or they may shorten content to make it fit into a smaller space, such as a package label or brochure.
In a unified content strategy, authors are not required to format the content; style sheets automatically format it based on the content’s desired context and medium. Instead, authors focus on the information—specifically, its meaning and structure. Structure is critical because it unifies the content, regardless of who is writing it. When content is structured consistently, it is transparent that a number of different authors may have worked on it. In this way, structured writing enables collaborative authoring and prepares content for reuse, regardless of who writes it, enhancing authors’ productivity. In a structured writing environment, whoever writes a warning—or an overview, or a procedure, or a copyright notice—writes it the same way. Plus, when similar types of content are always structured the same way, users quickly learn how to read or find information which can potentially reduce your support costs.
The degree to which you break down (and enforce) the structure of your content depends on the “granularity” of your material and your desire for consistency. (Granularity refers to the smallest piece of information that is reusable. For more information on granularity, see Chapter 8, “Information modeling.”) The structure of the various information products is defined in an information model and, depending on the authoring environment, authors may be prohibited from including content that is not defined in the model.
For instance, if the model is supported by a Document Type Definition (DTD), the DTD will allow authors to create documents only according to the structure defined in the DTD. If the model is not supported by a DTD, authors may select from style tags, complete areas within a form, or enter text into a template that tells them what content must appear in the document. In an authoring environment not supported by a DTD, authors would rely on the model itself for the hierarchy.
Many problems arise when content is not structured. Some procedures include results within a step; some don’t. Some procedures include an introductory or stem sentence; some do not. Sometimes steps are numbered; sometimes they are not. Sometimes warnings are included; sometimes they are not, and when they are they might contain inconsistent types of information. If the structure for writing a procedure (and for writing all the components within a procedure) is standardized, then authors can focus on the content that belongs in each step, not on how to put the procedure together. Also, readers get used to reading information in the same way, reducing their cognitive load. [1]
Before getting into the concepts of structured writing, it’s beneficial to understand the meaning of structure. According to Merriam-Webster’s online dictionary, the noun “structure” has the following five definitions:
the action of building
a: something (as a building) that is constructed; b: something arranged in a definite pattern or organization
manner of construction
a: the arrangement or particles or parts in a substance or body; b: organization of parts as dominated by the general character of the whole
the aggregate of elements of an entity in their relationship to each other
Merriam-Webster’s also lists a definition for “data structure” that is applicable to information: “Any of various methods of organizing data items (as records) in a computer.” Applied to information, this could easily read, “Any of various methods of organizing content in an information product.”
In fact, all these definitions lend themselves well to writing, in particular, the manner of construction (that is, how content is put together), the arrangement of parts (that is, the hierarchy of elements), and the aggregate of elements of an entity in their relationship to each other (that is, how certain elements relate to other elements).
So, you know what structure is, but what is structured writing? “Structured” writing, as its name implies, is the way pieces of information or content are put together to form an information product—a whole sentence, a whole paragraph, a whole procedure, or a whole book. Structured writing is based on information theory, as follows:
Structured writing is based on cognitive psychology.
Structured writing is based on how people read, process, and understand information. Within a structured writing environment, authors follow standards developed for certain types of content, ensuring content is always presented consistently. For example, principles of cognitive psychology guide us in determining how many steps a procedure should contain before providing users with a break. In a structured writing environment, the size of a procedure becomes a guideline, or even a rule, ensuring the consistency of the procedure for both authors and users.
Structured writing follows standards.
Information standards, once defined, are consistent. Once you define the structure of the content (for example, the structure of a procedure), whoever writes a procedure must follow that structure. Not only do you define how many steps there should be in a procedure, you define what the structure for a step is. The standard tells authors such things as “A step must always contain the condition under which the step is performed, the action, and the result of the action…in that order.” Whoever writes the step writes it in this way, so ideally, that step can be reused in any other related procedure. The structure can apply to individual steps, to the whole procedure, or to individual elements within a step, which brings us to our next point…
Structured writing applies at numerous levels, depending on your needs.
For example:
sentence/step
paragraph
chapter
document, volume, set, and more
In a structured writing environment, standards apply at the level where you want consistency and reuse. If you plan to reuse information at the sentence level, then sentences must be structured consistently; likewise, if you plan to reuse information at the paragraph level, then paragraphs must be structured consistently. The granularity will dictate the level of structure you must define. Chances are, if you’re reusing information in user guides, marketing materials, press releases, external web sites, and intranets, the granularity will be at the paragraph level. To accommodate all uses, a paragraph must be structured in a similar fashion, following guidelines for the type of information it conveys. When paragraphs are structured consistently, they can come together to form a unified information product, regardless of who has written each paragraph. Without structure, information products can take on “ransom note” characteristics, similar to the appearance many publications had in the early days of desktop publishing. Without structure, elements also read dissimilarly, resulting in a lack of cohesion. The more granular your information, the more structure you will need, as well as more adherence to structure.
Structured writing is governed by principles that describe how people process information:
Chunking
People can best hold 5 to 9 chunks of information in short-term memory. Accordingly, structured writing groups information into small, manageable units, and compiles those units into larger structures, also based on the 5-to-9 principle. Each chunk is an independent unit of information that can either stand on its own or contribute to a larger unit. If a procedure contains more than 10 steps, it’s likely that those steps can be broken down further. Imagine having to read 32 steps just to program the stations on your car radio. That much information is not only intimidating, it’s also difficult to follow and still keep track of where you are. Four smaller procedures—each with 8 steps—categorized according to subtopic would be much more usable, not to mention user friendly.
Labeling
Chunks of information are labeled to identify the type of information they contain. To be effective, labels (for example, titles, headings, and subheadings) are substantive, indicative of the information they contain. For instance, rather than calling a procedure “Radio Stations,” you could call it “Tuning Your Radio Stations.” Substantive labels give users a clear indication of what to expect when they select a particular piece of content. Clear labels also make it much easier for users to scan for the correct information. Every chunk of information should have a substantive label. In fact, if you can’t think up a good label, you may not need the chunk itself.
Relevance
Only information that relates to one main point is contained in a chunk, eliminating “nice to know” information. If authors want to include “nice to know” or “commentary” information, they can include it in an appropriately labeled chunk, allowing users to decide whether it’s relevant for them. According to the relevance principle, the chunk labeled “Tuning Your Radio Stations” would contain information that describes how to tune radio stations—and nothing else. Commentary about various radio stations is not relevant. If authors wish to include commentary, it must be in a separate chunk and labeled accordingly, something like “Jazz Radio Stations on the Eastern Seaboard.” Relevance is important from both reuse and usability perspectives. If procedures, for example, contain only relevant details (as defined in an information model), then procedures and parts of procedures can be reused effectively because they are consistent from procedure to procedure. Their usability is also enhanced because relevancy teaches users to always expect the same type of information in a procedure, overview, recipe, and so on.
Consistency
For similar subject matters, use similar words, labels, formats, organizations, and sequences. If you decide that procedures should always be in numbered lists (with a certain type of numbering), then procedures should always appear in numbered lists. If cautions are to be worded in a certain way (again, as defined in the information model), then cautions should always be worded that way. If you decide that proposals should be organized in a particular order, then they should always be organized in that order. Note, however, that even though the consistency principle also applies to format, authors still separate content from format during the writing process. Instead of being part of the writing process, format is usually defined in a style sheet that formats content according to the rules that authors develop for each type of content, for each user group, for each information product, and for each medium. When determining format rules, authors analyze information to figure out the best way to present it; style sheets are then developed for the content outputs, so even though format is applied after content is written, it is still based on content.
Consistency, like relevancy, is critical for both reuse and usability. If you are reusing steps from procedure to procedure, then the steps must be consistent in style, format, and wording, or the reuse will be jarring and the procedure potentially unusable. Likewise, if a caution from one document will be used in several other documents, then it must be consistent with the other cautions that appear in those documents. From a usability perspective, when information is presented consistently, readers form expectations about what it contains, which reduces their learning curve as well as their cognitive load. They may decide to always skip a certain type of procedure because it is not applicable. If writers change what that type of procedure contains, users may miss relevant information.
Reuse
Building on the consistency principle, the reuse principle dictates how a chunk of information can be reused in similar information products, so that wherever it is repeated, it is the same. The reuse principle also ensures that when a chunk is updated, it is updated in all places it appears, guaranteeing ongoing consistency. Reuse is indicated in the information models (and supported by authoring and content management tools), along with writing standards that address all the principles of structured writing, such as how big that element should be (chunking), how it must be labeled (labeling), what type of information it must contain (relevance), and how it is to be structured (consistency). In this way, elements are both reused consistently and written soundly.
In a structured writing environment, chunks of content are assigned “rules” about their structure, based on how that chunk will be used and the type of information it contains. Rules are based on the belief that not all information is created equally and that it should be treated differently. Accordingly, if information is conceptual, it will follow the structure rules for conceptual information. And, if information is procedural, it will follow the structure rules for procedural information.
Ideally, authors consider information types when applying the principles of structured writing to their content. How each type is structured is then documented in the information model and supported by a style sheet that applies a design suitable to the information type. For example:
Procedures and processes are best presented in sequentially numbered action tables and lists.
Concepts and principles often comprise text-based information chunks, with examples and illustrations included to support the concept.
Classifications are often presented in lists and tables.
Comparisons are best presented in tables that directly compare one component with another.
Table 20.1 provides an example of writer guidelines for semantic model.
Table 20.1. Authoring and structure guidelines for a warning
|
Element |
Authoring and structure guideline |
|---|---|
|
Icon/Signal word |
The signal word (for example, Warning) lets the user know that the related information is important. Using the icon in conjunction with the signal word enables the reader to locate them both quickly. Both these elements are automatically inserted by the style sheet. For a list of warnings or precautions, one signal word at the head of the list is sufficient. Presenting the list in a bulleted fashion helps reduce the “information overload” that would otherwise be experienced if a series of individual alerts were to be presented one after another. |
|
Title |
Identify the hazard with a title. This gives users an easy way to identify the different types of hazards that may apply to them. |
|
Alert body |
Tell users how to avoid the hazard or tell them how to identify the potential problem. Include specific information on what not to (or what to) do. This is usually in the form of “Do not…,” Never…,” and so on, and is followed by the specific actions that will enable the reader to avoid the hazard. Where appropriate, add hazard identification information that will enable users to identify the hazard or problem so that they may avoid it. Tell users the consequences of ignoring the warning. Explain the problems, limitations, or effects that may occur as a result of ignoring or disregarding the warning. |
As described so far in this chapter:
Content must be structured so that it can be reused.
Structuring content not only makes it consistent for reuse, it also enhances its usability.
The guidelines for creating structured content are contained in models.
Depending on your need for control and precision in your unified content strategy, and on the tools you’re using, you can provide explicit models that guide authors through the process of creating structured content (for example, DTDs, authoring templates, or forms), or you can provide written guidelines that authors follow manually (instead of being guided by a tool).
Writing to a model is critical in adopting structured writing because the model contains the rules that govern not only what elements belong in which information product, but also how each element is structured (based on the type of information it contains). When implementing structured writing, models serve three purposes:
Provide guidelines for authors.
Authors use information models to determine what information goes in which information product, as well as how to structure each element. Referring to the information model, they can, for example, determine that an information product requires error codes, determine the structure of an error code, and get hints or rules about how to write an error code. Models should also contain examples of elements as they should be written; these “best practices” help authors to compare their elements against what they should be, whether they’re writing from scratch or revising existing elements.
Provide guidelines for architects.
Information architects use models to build the DTD or template that authors must follow. Instead of referring to written guidelines, authors are guided by the tool through what to include and how to structure it. Some tools even allow architects to include examples or help that shows authors samples of completed elements. Even in a structured writing environment supported by tools, authors still need to understand the model to follow what the tool is asking them to do.
Provide guidelines for reviewers.
Model reviewers check information models to ensure they support customer and information requirements. Documentation reviewers use models to review authors’ drafts. They compare the draft against the information model to ensure it contains all the necessary elements.
Figure 20.1 shows the information elements for a product description model and how they are reused to accommodate different needs. In writing to this model, authors know that a product description must contain a product name, a product description (divided into long, short, and medium components), and a graphic, in that order. Each element within the product description must be structured this way to accommodate its different uses. If this model is supported by a DTD (or other automated authoring tool), the DTD would guide the authors through the product description, prohibiting entries that are not included in the model. If the model is not supported by an authoring tool, authors would refer to the model to know how to put each element together. The model would go on to provide writing guidelines and an example for each element, showing authors such things as how the long product description should be structured and written, based on the type of information it conveys.
For further information on models, refer to Chapter 8, “Information modeling.”
Another way of separating content from format is to use the building block approach. The building block approach allows you to identify a core of information that is applicable for all information products and users, then build on it to customize information for different uses and users. You start with core information and then build on it, as follows:
Identify the core information (the information that is applicable for all uses).
Identify what has to be added to the core to meet other needs, such as training or different audiences.
Tag additional elements according to where they belong, as in a patient guide or programming guide.
For example, you might start with a product description that contains the elements in the model shown above in Figure 20.1. That entire product description becomes your core information, to which you then add elements to create the following materials:
User guide information
To the product description, you add specifications.
Training materials for the product
You might add instructions for getting started with the product.
Internal staff support materials
You might add frequently asked questions about the product so staff can respond to customers’ questions.
Table 20.2 shows a building block approach for creating the documentation accompanying a software package. The online user guide contains the core information, and the internal support and training materials build onto the core.
Table 20.2. Building blocks for software documentation
|
Online user guide (attached to application) |
Internal support materials (intranet) |
Internal training materials (classroom) |
|---|---|---|
|
Field definitions |
Field definitions |
Field definitions |
|
Screen-level information (details about each field on the screen) |
Screen-level information as part of an overall task |
Screen-level information as part an overall task |
|
Screen images |
Screen images (optional) |
Screen images |
|
Overviews (optional) |
Overviews |
Overviews |
|
User tasks |
User tasks |
User tasks |
|
Troubleshooting for tasks |
Troubleshooting for tasks | |
|
Objectives | ||
|
Task context | ||
|
Examples | ||
|
Exercises | ||
In the building block approach, each element is identified by the information product in which it belongs (for example, training, user guide, intranet), and supported by style sheets that format it for the appropriate media. In this way, authors create content elements, augmenting the core sequentially. The format is applied after the content is published to its output. (Different media have different requirements for displaying content effectively. For example, the Web has different display requirements than a printed user guide, and a printed user guide has different display requirements than a printed training guide. Hence, different format requirements are required for each output.)
So, what about using a product description in a number of different places and publishing it to a number of different media. Can the same content really be written so that it’s appropriate for all its potential uses? Can a product description that is used in a brochure really be reused in training materials? Shouldn’t the brochure have a different tone?
We believe that content can be reused effectively, simply by following writing guidelines that are applicable to all the potential uses for the content. In addition, the building block approach allows for content to be augmented as required, so the core is written in a style that is applicable for all uses and the augmented parts are written to accommodate their specific uses. Training materials, for example, can use the same product description as the brochure, but where they differ is in the exercises and explanations that characterize training materials. Likewise, the brochure can use the same product description as the user guide and the training materials, but where the brochure differs is in the addition of “marketing” details that explain to potential customers why they should buy the product. But, the product description is the same, regardless of where it is used. The writing guidelines for each reusable component are documented in the information model (along with the structure guidelines) and are based on the type of information each component contains, as well as its potential users, uses, and reuses. Where the difference occurs is in how much information is provided and how it is presented. Figures 20.3 and 20.4, in the section “The Finished Product,” provide excellent examples of how the content can be reused in many different places.
After developing content for both online and print media for more than 20 years, our experience has taught us that well-written online documentation also makes good paper documentation and vice versa. Consequently, we’ve developed guidelines to ensure that content really can be used in a number of different ways. Many of these guidelines are simply guidelines for clear communication and make for better content, regardless of reuse. Some sample guidelines (not all-inclusive) are summarized in Tables 20.3 and 20.4 and are described in detail in Appendix B, “Writing for multiple media.”
The guidelines for online documentation (such as online help) and web materials are very similar:
Table 20.3. Guidelines for online documentation and the Web
|
Online documentation |
Web |
Wireless (such as, PDAs) | |
|---|---|---|---|
|
Write succinctly |
|
|
|
|
Write so users can scan |
|
|
|
|
Layer information |
|
|
|
|
Write useful titles |
|
|
|
However, if you look at these guidelines closely you will find that they are just as valid for paper.
Table 20.4. Same guidelines applied to paper
|
Paper |
Reasoning | |
|---|---|---|
|
Write succinctly |
|
Clear concise content can greatly improve the quality of paper materials. |
|
Write so users can scan |
|
Long passages of text that extend down a page or over pages is hard to read. Chunking that information can make it much easier for a reader to comprehend. |
|
Layer information |
|
This is a bit harder on paper. You don’t want to have a lot of “gotos” in the text that take the reader back and forth. However, layering of content is appropriate for things such as overviews, summaries, and check lists, as opposed to the detail of the body. |
|
Write useful titles |
|
Useful titles make it easier for users to find what they want. |
Note that these guidelines also relate to the principles of structured writing:
Writing succinctly relates to chunking and relevance; only relevant content is included in “bite-size” chunks.
Writing so users can scan is handled through labeling, chunking, and relevance.
Layering information is achieved through chunking, labeling, and relevance (layering according to hierarchy of relevant information).
Writing useful titles is accomplished by following the labeling principle.
All guidelines help writers to achieve consistency and reusability, especially when standards accompany each guideline.
The Reo Auto Company is preparing for the annual auto show and launch of its new vehicles. This year they are launching their first sports utility vehicle (SUV)—the Tsai. They require a variety of information products: a press release to announce their new lineup, brochures to hand out at the show and dealer showrooms, updates to the web site, and a show catalog. The web site team and marketing group sit down to figure out a unified content strategy for the materials. They determine that the information products are to be provided in three media: paper (show catalog, press release, brochure), web (web site, press release), and email (press release). Each information product requires different content and design:
Show catalog for the entire line-up (photo, short description, and key features, three cars to a page)
Brochure for the Tsai only (photo, long description with all the features and benefits)
Press release for the Tsai only (no photo, short description, features and benefits)
Web site for entire line-up (home page for each car with photos, list of full features combined with a pricing calculator)
Figure 20.2 shows a portion of the information model for the Tsai product description.
Working with the model, the web site team and marketing group proceed to develop the content, as shown in Table 20.5. (The metadata column indicates in which information product the content will appear.)
Table 20.5. Content development for Tsai product description
|
Element |
Content |
Metadata |
|---|---|---|
|
Product Name |
Tsai |
All |
|
Product Description | ||
|
Product Desc. Short |
The new Tsai is a totally new experience in SUVs. The revolutionary Tsai combines a gas engine with an electric motor, resulting in a fuel-efficient and environmentally conscious SUV. Yet none of the features like roominess and ruggedness are lost. The best of all worlds, the Tsai. |
All |
|
Product Desc. Med |
The Tsai features an all-wheel drive with an inline four-cylinder engine. The powertrain includes a five-speed automatic transmission and has a towing capacity of 1,000 pounds. Integrated light-weight roof rails and fold-down rear seats with 70/30 split make carrying loads a breeze. |
Brochure |
|
Product Desc. Long |
The revolutionary light-weight body is manufactured with dent-resistant polymer. Front and side air bags add to safety and security. The car-friendly height makes it easy to get in and out of and to load all your essentials on top. |
Brochure |
|
Graphic |
TBD. |
Show catalog Brochure Web site |
|
Graphic |
TBD. |
All [2] |
|
Features | ||
|
Feature title |
Features. |
Brochure |
|
Press release | ||
|
Feature item |
2L engine. |
All[2] |
|
Feature item |
Anti-lock brake system. | |
|
Feature item |
Power brakes. | |
|
Feature item |
Stabilizer bars. | |
|
Feature item |
Low emission Vehicle Standards. | |
|
Benefits | ||
|
Benefit item |
The only SUV that is truly environmentally friendly from its construction to its operation. |
Brochure Press release Web site[2] |
|
Tag line |
Practicality of a car, power of an SUV. |
Brochure Press release Web site |
[2] Not shown in illustration, but included on additional web pages | ||
In a unified content strategy, structure is critical because it unifies the content, regardless of who is writing it. Information is chunked and written in elements, which are then assembled—according to a predetermined hierarchy—into information products. Each element, and each information product, is structured in a consistent way, which both enables it to be reused and allows for consistency. The information models specify how information products and information elements are put together to ensure that consistency.
To structure information effectively, you need to separate content from format, which means you need to:
Define standards that focus on meaning rather than format.
Think about what you want the information to do rather than what you want the information to look like.
Create standards for each element, so wherever the element appears, it is consistent, and so it is also consistent with the other elements contained in the information product.
Define standards to identify what content an element contains and how it should be put together, as well as an example.
Create a writing environment that enables authors to structure their content consistently, by either supporting them with tools or providing comprehensive models for them to follow.
Decide how the elements should appear in their various outputs and develop style sheets that are applied when the content is published to its various formats.
Follow writing guidelines to ensure content is written effectively for all media and all uses.
[1] For more information on how consistent structure facilitates comprehension, see Dr. Robert Horn’s studies on structured writing, available at http://www.infomap.com and http://www.stanford.edu/~rhorn.