Structuring Your Documents to Maximize Reuse

CIDM

June 2000


Structuring Your Documents to Maximize Reuse


CIDMIconNewsletter Janice (Ginny) Redish

Single Sourcing Requires Structured Documents

A major topic among information development managers these days is single sourcing-writing information once and using it many times. Structured documents are critical for single sourcing. So, let’s explore

  • what we mean by structuring documents
  • why structuring is useful
  • some of the concerns that writers have about structuring documents

Note: Even if you aren’t yet considering single sourcing, you’ll find that structuring documents is an extremely useful, time-saving technique. It works in traditional publishing and is useful for individual writers in any situation where they have to create the same type of document many times. It is essential for teams of writers who are contributing parts to a large document or to a set of documents.

What Do We Mean by Structuring Documents?

Structuring documents is a process that involves several steps:

  • listing all the different information elements that a particular type of document might have
  • naming the information elements
  • setting the guidelines for organizing documents-deciding which information elements may (or should) appear in a particular type of document and in what order
  • setting style standards for each information element
  • linking the named information elements to templates, specifying how a document will look on paper or on the screen

Listing the information elements
We all use a variety of information elements in our documents. A document might have a title; headings at various levels; different types of text, including introductory paragraphs, procedural steps in numbered lists, tips, hints, notes, and examples; different types of graphics, such as icons, screen shots, and technical illustrations; captions and callouts for those graphics; and so on.

Pick up any document that you work on and identify the different information elements that make up a typical page of that document.

Figure 1 shows an example of the information elements on a page of a print document.

first-page15

Naming the information elements
To make structuring work, each information element must have its own name so that it is listed separately in templates and style sheets. An important issue to consider is the level of granularity that you need. Is a general name for a type of text sufficient? Or should you name the information elements by the specific content that they convey?

For example, for most of this article, I am working with typical style sheet elements like body text and bulleted list. Body text is any prose paragraph no matter what the content. Bulleted list is any list (other than one with numbers) no matter what the content. However, I decided that I wanted the names of the styles (that is, body text and bulleted list) to be set in a different font from typical body text paragraphs. So, now I have another information element, name of style. I keep it separate from body text as an element of my document so that I can set-and change-the formatting for it differently from other parts of the document.

In single sourcing, where you are developing a content-management system, you may want to separate and name elements by content, even if they have similar formatting in most documents. Information elements that you want as separate entities might be as small as a few words, such as the name of the company. The advantage is that if the name changes or the font in which the name must be used changes, you can change that in all your documents without disturbing any other part of the document.

Setting guidelines for organizing documents
One of the main advantages of structuring documents is that it promotes consistency in formatting-in the way the document looks on paper or screen. We’ll get to that advantage in a later section. Another advantage is that, through the process of structuring documents, you can also promote consistency in both organization and style.

As information development managers, you know that documents must be carefully planned. You expect writers to organize and outline their documents. When you work within the process of structuring documents, you add questions like these to the organization phase:

  • What information elements are relevant to this type of document?
  • What purpose does each information element serve in this type of document?
  • What arrangements (organizations, sequences) of information elements are best for users of this type of document?

For example, the document in Figure 1 is the setup manual for a personal computer system. When we planned this manual, we realized that the critical information elements were exactly the ones you see in Figure 1:

  • the task
  • a brief introduction to the task
  • steps for completing the task
  • a graphic (or graphics) to illustrate the component and relevant actions
  • a footer with book title and page number

Other information elements, such as operating procedures, conceptual information, rationales, and so on, were not relevant to this type of document (given the goal of helping users get set up and running in a very short time).

The order in which the information elements appear is structured to match the user’s logic. Every section of this manual has these four elements in this order with the provision that steps and graphics may be interspersed if a graphic is needed for a step part way through the procedure. (That’s what you see here. Step 3 with another graphic is in Figure 2.)

second-page9

In other documents, different parts of the document might have different information elements to match their different functions, but similar parts of similar documents should be organized in the same way. Structuring helps to achieve this level of consistency and patterning, which in turn helps both writers and users.

Setting style standards for each information element
It also helps both writers and users to have consistency in the style for writing each type of information element. Figure 2 shows our example with style standards for some of the information elements.

Ironically, the automatic structuring tools that we have (style sheets in word processors, templates and document definitions in content-management systems) are all about formatting, not about writing style. For writing, we must rely on publishing and distributing standards and style guides, training writers, and having good editors. Don’t neglect this aspect of structuring documents, however. Good style standards for each information element are critical.

Linking the named information elements to templates
One of the main goals of structuring documents is to have all the exemplars of a given document type look alike. Once you have structuring in place, writers construct documents by using the organization guidelines, style standards, and template and by assigning everything in the document to the appropriate type of information element. Therefore, the writers can concentrate on the content without worrying about the format.

Another goal of structuring documents is to reuse content. That might mean taking one chunk of content (for example, a paragraph, list, or graphic with caption) and using it in several documents. It might mean taking an entire document and publishing it in different media with formats that are appropriate to each medium.

Why Is Structuring Useful?

The bottom line for most companies is that structured documents save money. They also make life easier both for writers and for users. Here are some of the benefits:

  • Writers can focus on users and content rather than fussing endlessly about page layout or having to remember how they formatted a similar piece or an earlier part of the same document.
  • Writers are more productive. There’s less rework.
  • Writers can borrow content from each other or from themselves. There’s less redundancy and chance of errors in the content.
  • Editors can concentrate on high-level issues because consistency of formatting is assured.
  • If writers follow guidelines for organization and style, editors need to do much less to achieve consistency within and across documents in those areas, too. They can focus on overall usability, relevance, accuracy, and coherence.
  • Reviewers save time. When content is reused, it may not need to be reviewed each time.
  • Writers or product specialists are much more productive at the end of the process. There is much less need to go in and “fix it up to look like it should.”Note, however, that the need for production specialists and “clean-up time” doesn’t disappear entirely. Some tweaking to make information fit on a page or screen, to keep relevant content together, to make pages or screens both usable and aesthetically pleasing is still needed. None of the available tools does a perfect job of conversion from one software package to another. Reviewing the formatted version of output files is still a necessity.
  • Writers can easily change the format of a document. Consistency is maintained when the document is changed.
  • Users get documents with a consistent look and feel.

Why is a consistent look and feel important? It’s good for the company because it promotes an image of competency. It’s also good for users. People are pattern-oriented. We see patterns even where they don’t exist, and we quickly build expectations from what we see. Inconsistency in formatting leads us to wonder why something is different, and that takes time away from dealing with the content. It is easier to grab information quickly from a document when we know where to look for whatever we are looking for.

To achieve these benefits, however, you have to have documents that are well-structured, and writers and editors have to use the templates and style guides. It takes time and resources to set up a carefully structured document and to train writers and editors, but the initial investment will be repaid rapidly in savings on each later document. (See below on how to set up structured documents.)

What Concerns Might Writers Have About Structuring Documents?

I’ll consider three questions that writers often have about a move to structured documents:

  • Doesn’t structuring stifle creativity?
  • I’m the only one who writes this type of document. Why should I think about structuring it?
  • I’m working on the Web. What’s the relevance?

Doesn’t structuring stifle creativity?
No! In fact, structuring frees writers to concentrate on the parts of the process that they often wish they had more time for. They can pay more attention to meeting users’ needs and to the information itself. They must still do audience and task analyses. Even if an overall organization and style is set for a type of document, they must still decide what information to include and what words to use to convey that information. And if they spend less time on writing and page layout, they might have more time to sit with users before writing and to do usability evaluations with users when they have a draft.

Writers and editors should be involved in the process of structuring the documents they work on-in deciding on appropriate information elements, on guidelines for organization and style, and on the templates. In fact, to develop good documents, you might want to include the skills of information architects, document designers, typographers, and usability specialists, as well as writers, editors, and users.

In my experience, although writers have sometimes expressed this concern about creativity before a project to structure documents, when the structuring is in place, they are thrilled. They quickly see that working with structured documents is liberating; it makes their work much easier.

I’m the only one who writes this type of document. Why should I think about structuring it?
Structure is valuable even for single authors. Why spend time creating the format each time you write a letter or a memo or send a bill or an invoice? Word processors make it easy to create templates based on a sample document.

Consistency in the format of your documents makes you look good to clients and users. For example, if you send an invoice to the same client every month, you save both yourself and the client time and effort if you use a template. Moreover, a template can help you remember what information you have to include.

I’m working on the Web. What’s the relevance?
One secret of successful Web sites is Web pages with clear structure. Part of the analysis phase in planning a Web site should include these stages:

  • identifying all the information types to include on the site
  • grouping them into types of pages (for example, on an e-commerce site, you will have list pages, item description pages, fill-in form pages, and so on)
  • developing an organization, style, and template for each of those page types

Several people may be involved in writing, editing, and producing pages to get a Web site up or updated in what always feels like impossible deadlines. Working with structured pages saves tremendous amounts of time while providing the consistency that makes the site look good and work well for users.

For further reading

Glick-Smith, Judy, 1999, How to Successfully Implement Document Management, in Best Practices, vol. 1, 69-74.

Redish, J. C., 1999, Document and information design, in J. G. Webster (Ed.), Wiley Encyclopedia of Electrical and Electronics Engineering, NY: John Wiley & Sons, vol. 6, 10-24.

Rockley, Ann, 1999, Single Sourcing, in Best Practices, vol. 1, 17-20.

Schriver, K. A., 1997, Dynamics in Document Design: Creating Text for Readers,
NY: John Wiley & Sons.

Weiss, E. H., 1991, How to Write Usable User Documentation, Phoenix, AZ: Oryx Press.

We use cookies to monitor the traffic on this web site in order to provide the best experience possible. By continuing to use this site you are consenting to this practice. | Close