Editing Modular Documentation: Some Best Practices

Introduction

Much has been said about the creation of modular documentation - from content management systems (1), (9), to information architecture (11), to delivery forms (5), to the usability of modular content (content being easier to use, easier to understand, and easier to find (6)), and so on. However, not much has been said about the editing of that content, and what the editor's role is in such an environment.

Carter (2) and Mott and Ford (7) both suggest that writing modular documentation is different from writing linear documentation because writers are now developing content as opposed to writing in the traditional sense. Therefore, editing content requires developing a mindset different from that of traditional editing.

The Mechanics of Modularization

The main goal of technical documentation is to provide access to technical content in an easy, efficient, and logical way. By separating descriptive from procedural information, organizing this information into discrete, standalone modules called topics, and then linking related topics to each other, writers can help readers quickly and easily find and use the information they need. Writing in a topic-based modular manner also helps writers better organize, construct, and write their documentation because it forces them to think about how to present the information in a clear and succinct way.

Modularization is based on these main concepts (1):

• Chunk text into logical standalone topics.
• Label topics with clear and meaningful titles.
• Link related topics to each other.

Chunk Text into Logical Standalone Topics

Chunking is the process of categorizing blocks of information into independent standalone topics based on their content type, and focuses on separating descriptive information from task-oriented information. This separation helps readers access only the most important and relevant information, structured in a concise and easily readable format.

The three basic types of topics are concept topics, task topics, and reference topics (4, 5, and 6):

• Concept topics provide background information that readers need to know before they can successfully understand and use a product or service. These topics describe concepts in a descriptive or narrative format, and answer the questions: What is it? What does it do? How does it work? Why is this important?
  
  
• Task topics provide sequential, step-by-step instructions that describe how to do something, that is, they answer the question: How do I?
  
  
• Reference topics provide additional detailed explanatory information (4). These topics usually present the information in a structured lookup table or list format.

Label Topics with Clear and Meaningful Titles

Labeling is the process of creating unique, clear, concise, and accurate headings that correctly identify the content included in a topic. This structured format further separates descriptive from task-oriented information and provides immediate visual clues to orient readers, enabling them to easily search for and access the information they need.

Link Related Topics to Each Other

Linking is the process of connecting topics to other related or relevant topics, which enables readers to easily jump back and forth between related subject matter in a document and to find the information they need. While the hierarchy represents the structure and flow of the different standalone topics, the links are the glue that holds all of the different topics together to provide meaningful content.

Best Practices for Editing Modular Documentation

Based on these three main concepts of modularization, as well as on our combined editorial experiences, we have identified the following guidelines that we consider to be best practices for editing modular documentation:

• Topic types must not be mixed.
• Topics must be standalone.
• Introductory information must be clear and to-the-point.
• Topics cannot be too long.
• Paragraphs must be short.
• Titles must be unique and descriptive.
• Related topic links must be meaningful.
• Topic collections must be useful and reader-focused.

Topic Types Must Not Be Mixed

As stated previously, modular documentation must be chunked so that descriptive information (concept and reference topics) is clearly separated from task-oriented information (task topics). Readers who are looking for information about how to do something do not want to wade through too much descriptive information to get to what is relevant to them. Similarly, readers who want to know detailed background information about what a product or service does do not necessarily want to see step-by-step procedures about how to use it.

Editors must be aware of the difference between descriptive and task-oriented information when editing modular documentation. For example, when reviewing a task topic about how to reset the status of a monitored system process, we need to make sure that it contains only the step-by-step procedure readers need to carry out the task successfully. There must be no information about how the utility that does the system monitoring works, no information about other things the utility does, and no information about how to configure the utility.

An important point must be made here, though. All task topics need some sort of brief (one- to three-sentence) introduction about the purpose of the task is and its context. This descriptive information is an integral part of the task topic and is not a separate, standalone concept topic.

Topics Must Be Standalone

Because modular documentation is made up of chunked topics that are not read in any particular sequence, each one must be standalone. Readers must be able to understand the topic they are reading without having to read something else, that is, all the information they need is located in this topic.

However, topics should not repeat the same background information over and over again. To reduce this risk of repetition, only the most relevant information is written in the topic, and then cross-references to where readers can get more details are provided (links between topics are discussed in a subsequent guideline).

Editors must determine how self-contained a standalone topic must be and how much repetition of information is needed. When we edit these topics, we must keep in mind the question, "If readers started reading at this topic and had not read anything else prior to this, would this make sense?" Continuing with our example of the task topic about resetting a monitored process's status, we need to make sure that the answer to this question is yes. Readers must have enough contextual information about this task to understand and carry it out (provided by the brief purpose information before the procedure starts), and if they want more information about the utility, there must be a cross-reference to the relevant concept topic.

Introductory Information Must Be Clear and
To-The-Point

Chunking documentation into meaningful standalone topics requires the information in the topics to be organized in a logical and usable order. This chunking of information means that the first paragraph of a topic is the most important paragraph because it states the purpose of and summarizes the information presented in that topic. Procedures especially require standard introductory wording (1). This introductory information helps readers know if they are in the right place for the right information they need. The first sentence of the topic must also be clearly and directly related to the title, so readers can immediately see the connection between it and the topic content.

This first paragraph can also be used in building search terms in searching systems, and in some display implementations (such as the IBM® Eclipse Help System), the first paragraph can be used as hover help for links and as descriptive text for embedded child links. The introductory information serves the topic itself, and it is reused for many other retrieval techniques.

Topics Cannot Be Too Long

Chunking documentation naturally limits the length of topics, improving the readability and usability of the information. Topics must provide just enough detail, with information that is focused and precise. They must include only the information relevant to the readers, and they must exclude information that readers do not need to know.

So, how much information can really go into one topic? Readers will not read pages and pages of text, but if you make the topics standalone, how much information do you include before it becomes too much information? Unfortunately, editors are forced to use the classic response to many quandaries: It depends. It depends on the subject, the audience, the environment, and many other factors.

One of the best analogies to help organize topics so that length is not an issue in the topic collections is the principle of the inverted pyramid that is used in journalistic writing. The most important information is presented first, followed by the next most important, and so on, so that, if the editor of the newspaper article needs to reduce the word count to fit the space available, none of the important information in the story is deleted. Also, Web page design borrowed the concept of above the fold (or, more precisely, above the scroll) from newspaper publishing, and this design concept holds true for modular documentation as well. Readers almost always read the information above the fold (or what starts the topic) but only sometimes make to what is below (or what comes at the end of the topic).

Paragraphs Must Be Short

In addition to limiting the length of the topics by chunking documentation, paragraphs must also be kept short. Readers do not read every word of our documentation. They skim and scan it seeking the tidbits of information that will help them get their job done. Using white space and formatting techniques to ensure that the information is visually effective helps achieve the short paragraphs.

Once again the newspaper analogy is applicable. You never see a newspaper article with unbroken columns of text, but instead see several short paragraphs that flow from one to another (5). The same is true for modular documentation: you must keep your paragraphs short.

Titles Must Be Unique and Descriptive

As stated previously, topics in modular documentation must be labeled with unique, clear, concise, and descriptive headings that correctly identify the content included in that topic. Because topic titles are used in search results, titles must clearly differentiate the topics from one another and make sense even when taken out of context (1, 3).

Topic labels communicate the type of information included in the topic (for example, gerunds or verb forms communicate task information, such as Managing Clusters, and noun or adjective-noun strings communicate concept or reference information, such as Cluster Management). Topic titles also communicate the scope of the information included in the topic (for example, mentioning UNIX® in the title shows that the information applies only to UNIX-based systems). Placing the key unique words at the beginning of the title also helps readers find the topics that they want more quickly.

Ultimately, though, topic titles help readers decide if they need to (or want to) read the topic. This decision is analogous to reading a newspaper. When people look at a newspaper, they look at the headlines first. If the story is interesting and relevant to them, they start reading the rest of the article. The same holds true for modular documentation.

Editors must keep this guideline in mind when reviewing modular documentation, ensuring that no topic label is repeated, that every topic label uses the correct syntax for its topic type, and that every topic label is as descriptive as possible. Continuing with the previous example of a utility that monitors process status and the procedure for how to reset process status, we might suggest that the concept topic that gives the background descriptive information be labeled Process Monitoring, while the task topic be labeled Resetting Process Status.

Related Topic Links Must Be Meaningful

Linking topics together is an important component of modular documentation. This linkage enables readers to navigate between topics and retrieve relevant information.

Several different types of related topic links can be implemented for modular documentation:

• Inline links, or integrated cross-references, provide direct and immediate access to the related information but they also interrupt the flow of the topic.
  
  
• Related information links, which appear at the end of a topic, provide access to the related information but only after the reader has read through the topic and can separately consider what additional information they need.
  
  
• Parent/child links reveal the hierarchy or organization of topics within a topic collection and enable readers to get broader information or other related specific information.

Within the information model, information architects must define a consistent and logical linking model. This linking model must define if and how each of the types of links that are available will be used. For example, the model must describe whether both inline links and related information links are allowed. Or, it must show that if an inline link is used then that link cannot also appear as a related information link. Finally, the model must define the acceptable number of clicks for your readers and your information, and then design a linking model that supports that number.

Topic Collections Must Be Useful and
Reader-Focused

The final best practice guideline encompasses all three of the basic modularization concepts. Although modular documentation is made up of chunked, standalone topics that do not have to be read sequentially, a clearly labeled information hierarchy or story that links the topics in a document to each other must exist. Task topics almost always have related concept topics, reference topics are referred to by multiple concept topics, and so on. Even when a document is written in a modular style, it must still be organized in a logical and usable manner (6).

Goal-oriented or task-focused organizations of topics can help readers find and retrieve the information they need quickly and easily (6). Tasks can appear at the topmost levels of the hierarchy, and the concept topics and reference topics that support those tasks then appear directly under those task topics. Grouping, ordering, and labeling topics logically (in some order of sequence) and consistently within a product information set, as well as across information sets, is important to readers. Editors must ensure that the topics being reviewed follow this hierarchy and tell the appropriate story.

There are also times when readers need to be forced to read sequentially, for example, tasks that must be done in a particular order. In these cases, editors need to provide tools for writers to use to force sequentiality, such as creating standardized wording in the introductory information for task topics stating the number of the task and the task sequence, or a creating a rule for linking the first and last steps in each task in the sequence.

Note: This is the end of Part 1. Look for Part 2 in the March/April 2010 issue of DMV.

References

1. Ament, K. (2003). Single Sourcing: Building Modular Documentation. William Andrew Publishing, Norwich, NY, USA.

2. Carter, L. (2003). The implications of single sourcing for writers and writing. Technical Communication 50 (3), pp. 317-320.

3. Ford, J. & Mott, R. (2007). The convergence of technical communication and information architecture: creating single-source objects for contemporary media. Technical Communication 54 (3), pp. 333-341.

4. Greene, L. (2000). Challenges and advantages of modular documentation. STC Proceedings.

5. Hackos, J. (2002) Content Management for Dynamic Web Delivery. Wiley Publishing, Inc., Indianapolis, IN.

6. Hargis, G., Carey, M., Hernandez, A., Hughes, P., Longo, D., Rouiller, S., and Wilde, E. (2004). Developing Quality Technical Information: A Handbook for Writers and Editors. Prentice Hall - PTR, New York, NY.

7. Mott, R. & Ford, J. (2007). The convergence of technical communication and information architecture: managing single-source objects for contemporary media. Technical Communication 54 (1), pp. 27-45.

8. Redish, J. (2000). Structuring your documents to maximize reuse. Best Practices 2 (3), June, 41, 43-47.

9. Rockley, Ann. (2003). Managing enterprise content: A unified content strategy. Indianapolis, IN: New Riders.

10. Sapienza, F. (2004). Usability, structured content, and single sourcing with XML. Technical Communication 51 (3), pp. 399-407.

11. The Web Style Guide, located at http://www.webstyleguide.com/wsg3/index.html as of 08 January 2010.

UNIX is a registered trademark of The Open Group in the United States and other countries.

Comverse is a registered trademark of Comverse Technology, Inc. or its subsidiaries in the United States and may also be registered in other countries.