When creating unified content, writers sometimes struggle with the idea that content written for one medium can be appropriate for another. This appendix explains how to write for multiple media, ensuring that content can be written once and used as required, regardless of the medium in which it appears. It includes writing guidelines for various electronic formats, as well as for paper. Then it compares them to show how the guidelines are applicable, regardless in which medium the content appears.
In our experience, following guidelines for clear, effective writing makes content usable, regardless of the medium or format in which it appears. If you need to add or remove detail to make content more applicable to a certain user group, or a particular product, or for a particular medium, you can do so through nested or derivative reuse (see Chapter 2, “Fundamental concepts of reuse”), or through the building block approach (see Chapter 20, “Separating content from format”).
Online documentation (initially, help files and later, HTML-based documents) was the first new medium—beyond paper—for which authors struggled to write effectively. Guidelines [1] for writing effective online documentation include:
Write concisely.
Users of online documentation do not read; instead, they scan or browse. Because reading is 25% slower from the screen, text should be short and to the point. Don’t be chatty or verbose. Remove excessive adjectives, compound sentences, and compound phrases.
Make writing easy to scan.
It is difficult to read large volumes of information online. Users tend to visually scan the text to pick out important pieces of information. To assist them, use:
Bulleted or numbered lists instead of “burying” lists or steps in the body of paragraphs
Short tables or columns to display relationships of information (for example, comparisons or “if/then” situations)
White space (don’t tightly pack information, but don’t leave too much blank on the screen either; use screen real estate wisely)
Sub-headings to break up information and make it easy to scan
Short paragraphs (3-6 sentences)
A consistent design for similar types of information so that users become accustomed to always seeing certain types of information presented in the same way, for example, comparisons might always appear in short tables. See Chapter 20, for more information on consistent designs for different types of information.
Layer information.
Online information should be short and precise. However, sometimes you need to provide more information than can be covered in one screen or topic. You can layer information with one level presented and subsequent levels linked through additional windows.
Write useful titles.
Titles are a key access point for users into the information. Titles form the table of contents and are often used as keywords for searching. Titles must be substantive and indicate to users exactly what the document contains. Avoid titles such as “General,” which are…well…too general!
Provide continuity/connection.
Chunks of information in an online environment are short and discrete. In continuing processes, users may have difficulty identifying what has gone before and what comes after. Explicitly refer to preceding or following processes and provide links to the processes. Write all “see” and “see also” references consistently.
Use specific references.
Avoid using references such as “See figure below/beside/above/in this section.” Instead, refer to figures, graphics, or tables explicitly by name or link to them in secondary windows.
With the explosion in popularity of the Internet (followed by intranets and extranets), authors needed to find effective ways to write for the Web. Jakob Nielsen (author of Designing Web Usability, New Riders, 2000), a recognized leader in the field of web usability, provides these guidelines (available on his web site at http://www.useit.com). Note how similar they are to the guidelines for writing online documentation, discussed previously.
Be succinct.
Write no more than 50% of the text that you would have used in a hardcopy publication.
Make information easy to scan.
Users scan text and pick out keywords, sentences, and paragraphs of interest. Don’t make your user read long continuous blocks of text. Ensure paragraphs contain one main idea. Use bulleted and numbered lists to draw attention to important points.
Make use of hypertext structure.
Rather than sacrificing the depth of information, split information up into multiple pages. Use secondary pages for long and detailed information.
Write simple sentences.
Convoluted writing and complex words are even harder to understand online.
Use effective headings.
Make sure that headings clearly indicate the content of the sections.
Online and web-based information is also available (and becoming more popular) on wireless devices such as PDAs and cellular telephones. Guidelines for effective content are only beginning to be developed for these devices. The major problem is the small screen size. A PDA has an average screen size of 160×160; a cellular phone’s screen is even smaller. This means that writing concisely is even more important.
There are a number of other issues in writing for wireless devices, such as ensuring that users can find the correct content and navigate through content. These issues and many others require more research before they can be effectively addressed with guidelines. But using clear, concise writing, and providing short, yet substantive, headings are still critical.
Writing for paper adheres to principles of clear communication, just as writing online documentation and writing for the Web do. Some guidelines for clear communication include:
Make the document’s purpose obvious and clear.
Make sure your document has a clearly defined purpose, audience, and context. Include only information that supports the defined purpose based on the users’ needs.
Express only one central idea per paragraph or section within the document (based on the users’ needs) and make the central idea clear—right away.
Write a topic sentence for each paragraph or section; the topic sentence must state the central idea you are expressing. If supplementary information is available, tell users where to find it, but be careful that you don’t send them searching all over the document for related information.
Linking users to related information is much easier online, but even then, you run the danger of sending users off into hypertext, often forgetting where they started from. On paper and online, always make your reason for including references to supplementary information very clear, and make it an option. If content is necessary for the understanding of a particular topic, include it in one place, with all other relevant content.
Chunk information into manageable pieces.
Content should be grouped into small pieces that are easy for users to scan, read, and comprehend. A manageable chunk consists of five to nine pieces of information.
Use headings that tell readers the purpose of the information in the paragraph.
Choose specific headings (for documents, sections, paragraphs, lists, and so on) that enable users to tell, at a glance, whether the information is relevant to them. Include only information that supports the stated purpose, as indicated by the heading.
Use clear, concise language.
Use words with common meanings and use them consistently. Avoid jargon, legalese, foreign phrases, and pompous expressions. Always match vocabulary and style of writing to the users’ needs.
These guidelines also apply to online documentation and to the Web. All information, regardless of the medium in which it appears, should have a clearly stated purpose, should contain only information that supports that purpose, should provide clear references (links) to related information, should be chunked into manageable pieces, with headings to indicate the content’s purpose, and should be written in language best suited to the users’ needs.
As shown in Table B.1, the guidelines for online documentation and the Web are very similar.
The guidelines in Table B.1 were developed to address the differences between paper and online/web and to ensure usability. However, if you look at these guidelines closely you can see that they are just as valid for paper. Table B.2 explains how the guidelines for online documentation and the Web also apply to paper.
Table B.2. Online documentation and web guidelines applied to paper
|
Paper Reasoning | ||
|---|---|---|
|
Write succinctly |
|
Clear, concise content can greatly improve the quality of paper materials. |
|
Make information easy to scan |
|
Long passages of text that extend down a page or over pages are hard to read. Chunking that information can make it much easier for a reader to comprehend. |
|
Layer information |
|
This is a bit harder for 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 checklists. They provide information that is further explained in the body of the document. |
|
Write useful titles |
|
Users should be able to tell, at a glance, whether content is relevant to them. Useful titles make it easier for users to find what they want. |
Even though the guidelines of clear communication apply to online documentation, the Web, and to paper, there are still distinct differences in how people write for paper versus how they write for the web. However, after developing content for online media for more than 20 years, our experience has shown that well-written online documentation also makes good paper documentation and vice versa. Where the difference occurs is in how much information is provided in each medium and how it is presented. Content should be optimized for the medium in which it appears and presented in the most appropriate manner. For example, definitions can be presented as pop-ups in online documentation, but as in-line text on paper. But, the definition must still be written clearly, following guidelines for effective writing. In addition, there may be less detail online and more detail in paper documentation. The level of detail and the way content is presented may not just depend upon the medium; it may also depend upon the information product and the audience.
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. Where the difference occurs is in how much information is provided and how it is presented. This is a perfect opportunity for nested reuse.
There are also differences in style, such as marketing versus technical documentation and user documentation versus learning materials. Although the same information can be used in a number of different places, authors may want to customize it by adding details, examples, or exercises. In some cases, authors may want to rewrite material to accommodate a particular need, while maintaining a link to the source so they know when it’s updated. This is a perfect opportunity to employ derivative reuse.
Well-written content that is created with good writing principles in mind, and that follows models designed for reusable content, means that you can write material once and use it many times, regardless of the media.
[1] First appeared in Rockley, Ann. “Putting Documents Online: A Manager’s Guide” (European Conference on Hypertext ECHT’94, Edinburgh, Scotland).