Without order there is only chaos, and nothing constructive can evolve from chaos except order.
—Duncan Head
Organization is how pieces of information fit together to form a coherent arrangement of parts that makes sense to the user.
Organization applies both to the arrangement of information within a topic and to the arrangement of two or more topics (how topics fit together). You can build up larger structures by fitting together the parts. For example, you build paragraphs with sentences; you build topics with paragraphs, lists, tables, and graphics; and you build information centers, Web sites, help systems, and books with topics.
Figure 16 shows how you organize information within topics and then organize those topics to build a set of information.
Figure 16. Topics contain paragraphs, lists, and other elements; information centers, books, and online help contain topics.
Good organization can accommodate change easily. For example, if you create a separate topic for each task, you can easily add, remove, or rearrange tasks when the product changes or when you want to provide another organization scheme for a different set of users.
Poorly organized topics are often littered with paragraphs that are marked with a note label because the pattern of the information is too rigid to accommodate change. Poorly organized navigation elements (such as tables of contents or navigation panes) can hide topics that don't fit well into the existing structure.
Well-organized information is easy to find, especially when the organization is obvious to the user. Well-organized information is also easier for writers to reuse effectively for different types of output. Organizing information properly might take more time, but doing so will better serve the user and you in the long run.
To organize information well, follow these guidelines:
Organize information into discrete topics by type.
Organize tasks by order of use.
Organize topics for quick retrieval.
Separate contextual information from other types of information.
Organize information consistently.
Provide an appropriate number of subentries for each branch.
Emphasize main points; subordinate secondary points.
Reveal how the pieces fit together.
Topics are small, discrete, meaningful pieces of information, each with a heading. A topic, also known as a chunk, article, or module, must be long enough to cover a subject adequately and make sense if read by itself. Organizing your information into discrete topics gives you the flexibility to reuse the information or any portion of it for a variety of presentations. In addition, topics are generally short and therefore more searchable and more likely to provide users with just the information that they need.
Most technical information falls into one of three types: concept, task, or reference:
Concept
Provides background information that users might need to know before they can work with the product. For example, a topic called “Data consolidation” is a concept topic and might contain several paragraphs and a graphic that explain what data consolidation is.
Task
Provides procedural details, such as step-by-step instructions, along with information such as rationale, prerequisites, and examples. For example, a topic called “Changing authorizations” is a task topic and might contain a brief overview of changing authorizations, a list of prerequisites, steps to change the authorizations, and a list of any follow-on (postrequisite) tasks.
Reference
Provides quick access to facts that users might look up, such as conversion tables, syntax rules, message explanations, and code samples. For example, a topic called “Environment variables” is a reference topic and might contain a table that lists the operating systems, valid settings, and a default setting for each environment variable.
If you organize information into topics according to type, you can more easily keep your topics discrete, and you can provide a consistent structure so that users know what to expect. For example, if all of your task topics contain a brief overview, prerequisites, steps, and postrequisites, users know what to expect in a task topic. If you add conceptual information to the steps, users who are looking for concepts will have a harder time finding that information, and users who are trying to do a task are interrupted by conceptual information. Similarly, users who are looking for syntax and examples of commands will have trouble locating the reference information if it is combined with concepts or tasks.
The following topic contains task, concept, and reference information:
Original
The original topic contains too much information. Users will be more likely to find the information that they want if you separate the topic into a concept topic, a reference topic, and a task topic. The concept topic can have the heading “The union of two geometries,” the reference topic can have the heading “ST_Union function,” and the task topic can have the heading “Finding the union of two geometries.”
The revision shows three topics: a concept topic that explains what a union of geometries is; a reference topic that explains the syntax for the ST_Union function; and a task topic that explains how to find the union of two geometries. Each of the three topics provides links to the other two topics.
By splitting information into discrete topics that do not presuppose a specific structure or linear arrangement, you allow the topics to be organized or reused in different ways. A single topic can appear in multiple views of an information center, in a PDF file, in a printed book, and on a Web site. You can also share topics across sets of information for:
Multiple output media
Multiple product features
Multiple operating systems
Multiple audiences
In addition, you can add metadata to topics that allows users to dynamically build their own sets of information. For example, you can add metadata to a topic that specifies the operating system, type of user, product feature, and other facts about the topic. Users can build sets of information that fit their requirements based on the metadata that you specify.
Because users generally complete tasks in a certain order, the information should be arranged to reflect that order. If what users do in task Y depends on what they have done in task X, the topics should be arranged so that task X precedes task Y.
The following outline shows an organization that doesn't correspond to the actual order of tasks:
Original
The original outline shows that the task of configuring the product follows the task of testing the connections. In addition, the original outline lists the task of removing InfoProduct as a getting started task. Users are not likely to remove a product right after they install it, nor are they likely to look for the task of removing the product under the getting started branch.
Revision
Common sense suggests that users will have better luck testing their connections after they configure the product, as shown in the revised outline. The revised outline also does not include the removing task with the other getting started tasks.
Organizing tasks logically is important not only at the outline level, but also at the level of sentences and steps within each task topic. If the information in a task topic is not presented in the order that users need it, users waste time and become frustrated.
The following task topic shows a task in which the information and steps are not presented in the order that users need to know them:
Original
Installing InfoTax
To install the InfoTax software:
1. Run the setup.exe program. Follow the instructions that are provided on the installation screens. To access the setup.exe program, unzip the InfoTax software files by using a file decompression utility.
2. Before you install the software, ensure that you have enough storage space on your hard disk. The program automatically assesses your storage space, and the installation stops if there is not enough space. You will need 120 MB of free space.
3. Read the readme file to find out whether any differences apply to the installation for the operating system that you are using. The installation task is system dependent.
4. Create a directory in which to install the product. The name of the directory must begin with the characters tax.
System requirements:
2.0 GHz processor
256 MB RAM
Have your 16-digit product registration key available. You can find the key on the inside of the back cover of the InfoTax User's Guide.
Note: Shut down all other programs before you install InfoTax.
In the original task topic, information that users need before they install the InfoTax software is buried within the steps and is not in the order that the users need to use it. Users might start the installation task and waste time before realizing that they need a faster processor or more storage space. In addition, some key steps, such as shutting down all other programs before installing InfoTax, are in the system requirements section after the installation steps.
Installing InfoTax
Before you install InfoTax:
Have your 16-digit product registration key available. You can find the key on the inside of the back cover of the InfoTax User's Guide.
Ensure that your system has:
– 2.0 GHz processor
– 120 MB of free storage space
– 256 MB of RAM
Read the readme file to find out whether any differences apply to the installation for the operating system that you are using. The installation task is system dependent.
Create a directory in which to install the product. The name of the directory must begin with the characters tax.
To install the InfoTax software:
In the revised task topic, all of the tasks that must be done before the installation are explained before the installation steps. The tasks in this section need not be completed in an exact order as the original task topic implies, so they are shown in an unordered list in the revision. As a result, the installation task is streamlined, with the steps in the order that the user must do them to avoid making mistakes or losing work.
See the task orientation guideline “Provide clear, step-by-step instructions” on page 36 for more information about organizing steps.
In addition to organizing your main task topics by order of use, you need to fit concept and reference topics into your structure in a way that makes sense to the user. If you have concept and reference topics that are associated with particular tasks, you might arrange these topics with the tasks. Some concept and reference topics do not presuppose a particular task or do not fit well into a task structure. In these cases, you can arrange the topics for quick retrieval.
Concept and reference topics are often arranged either alphabetically or numerically. With an alphabetical arrangement, whether in a book or in an information center, a user who is looking at the topic “Infolist command” knows to go forward to get to the topic “Store command” and backward to get to “Grant command.” Similarly, with a numerical arrangement, a user who is reading about message 120 knows to go forward to get to message 395.
Other arrangement schemes (such as by chronological order, by component or category, or by job responsibility) might be helpful to experienced users.
The following set of reference topics has an alphabetical organization:
Original
The organization of the original reference topics is usable; however, the topics about commands are mixed with the topics about log files. Users who are looking for log files will need to look closely to find all of them.
Revision
The revised reference topics are organized by category. The command topics are first, followed by the log file topics.
Try to use categories that the user is familiar with or can distinguish easily as shown in the revision. When information is divided into arbitrary or ambiguous categories, users must work harder to find what they need. Users can miss information or become frustrated with the organization.
The following topics are categorized arbitrarily into those that might be used by new users and those that might be used by advanced users:
Original
In the original structure, users must know which topics are “beginning” and which are “advanced” to know where to find the information that they need. The division between the two categories is subjective and depends on users' assessments of their own skill levels with the product. Some users might look for the topic “Prompted query functions” under the Advanced category, whereas other users could look for “SQL statements” under the Beginning category.
Revision
In the revised structure, the two subjective categories are replaced by categories that make sense to all users.
In addition to organizing topics for quick retrieval at the outline level, you can help users by arranging the content of your topics to facilitate quick retrieval. If important information is difficult to find within a topic, users must spend extra time searching. In particular, reference information can often be presented in lists or tables for quick retrieval. See the retrievability guideline “Provide helpful entry points” on page 257 and the visual effectiveness guideline “Balance the number and placement of visual elements” on page 304 for details about how to make information easy to find within topics.
Other methods of aiding in quick retrieval are effective links between topics and effective index entries. These methods are discussed in Chapter 9, “Retrievability,” on page 245.
Contextual information explains the product windows and the fields and controls that the user is working with. This information might include the syntax for a field, conditions for when a control is available, what a control does, or even how to use a product window. Contextual topics can be short and are meant to be read when users are viewing the product windows or controls.
The following task topic provides contextual information inside the steps of the task:
Original
The original task topic shows the contextual information for each control mixed in with the task steps. Users who want information about what to specify in the Date field need to read through the steps to find the information that is associated with that field.
Another problem with mixing contextual information and task steps is that some controls on a window are not actually involved in the task. Some windows might be used for multiple tasks and therefore contain controls that are used in one task but not all tasks for that window. In addition, some controls might be extraneous to any task; for example, the Cancel push button is rarely part of a task. If you rely on the task steps as the only method of explaining the controls on a window, you can end up either with some controls that are not explained, or with unwieldy tasks that have extraneous steps for unnecessary controls.
First revision
The first revision shows the contextual information separated from the task topic. The first revision includes contextual help for the Change push button, which was not mentioned in the original steps for sending online checks because changing a payee is a different task. The task topic in the first revision is now streamlined because it focuses more on the steps to accomplish the task and less on details about each of the controls that are used in the task. The user can use the task topic with the contextual help topic to fully understand both the task and the controls on the window.
In some cases, you can provide the contextual help by using pop-up help for each control. The following revision shows what pop-up help might look like for some of the controls on the Checkbook window:
Second revision
By providing contextual help for fields and controls in the user interface as shown in the second revision, the writer streamlines the task help as shown in the first revision, avoids the need to provide a separate contextual help topic, and presents timely information about the window's fields and controls to users who need it.
Determine what information users need for each product window and control, and provide that information in a format that is easy to find. Ensure that contextual information is available from the interface or in a topic that users can link to from the associated task topics.
Consistent organization helps users become familiar with the structure of information so that they can find what they need with confidence. When you present information consistently, users learn to predict what information they will find and where they will find it.
Organizing information consistently also helps ensure that the information is complete. Therefore, this guideline is similar to the completeness guideline “Use patterns of information to ensure proper coverage” on page 90.
The organization of standard content, such as getting-started information or a contextual help topic, should follow a similar pattern across related products. For example, if you include restrictions before the steps in some task topics and after the steps in other task topics, users might not notice some of the restrictions.
The following navigation pane shows topics that are organized inconsistently:
Original
Because the information in the original navigation pane is organized by object type, the branch for deleting objects is out of place. Users who navigate with this navigation scheme learn to look for topics according to the type of object that they describe. These users don't expect to find the topics about deleting objects in a separate branch. For consistency, the topics about deleting objects should be presented with their appropriate objects as shown in the revised navigation pane.
Revision
In the revised navigation pane, the topics are organized consistently by object. Your navigation scheme might not be organized by object, but regardless of the navigation scheme that you provide, organize the topics within the navigation pane consistently.
If a navigation scheme contains a branch that has a single subentry, the navigation scheme might have an organization problem. If there is only one main thing to say at a branch level, a subentry is probably not needed.
The following book outline shows a chapter with one subsection:
Original
Chapter 8 in the original outline contains a brief introduction followed by one section. Therefore, the text in the “File structure table” section makes up most of the chapter.
Revision
Single subentries can sometimes replace the branch itself, as shown in the revised outline, where the subsection is now the chapter. The brief introduction in the original outline is either omitted or is added to the “File structure table” topic.
This outline shows a book structure, but the example applies to the organization of topics as well as to chapters and sections. Suppose that the original outline showed an information center navigation pane instead of a book outline. You would put the “File structure table” topic at the branch level instead of creating a branch with a single subentry for “File structure table.” By removing unneeded introductions and branches, you can streamline your navigation structure.
Branches can contain single subentries when the subentry presents a topic that is separate from the branch yet logically subordinate to the branch. For example, if your tasks have long examples, you might decide to separate the examples into their own topics. In the navigation pane, you show the examples subordinate to the tasks hierarchically. However, if task A has only one example and no other subentries, its branch will have a single yet logically subordinate subentry.
A more common problem associated with single subentries is not including enough topics at the appropriate level, as shown in the following outline:
Original
The original outline shows only one subentry for data security.
Revision
In the revision, the writer divided the topic “Access” into four separate topics. “Data security” now has four subentries so users can choose the specific type of access to read about.
Ensure that all single subentries are logically subordinate to their branch. If they are not logically subordinate, remove extraneous introductions and branches. If the single subentries are logically subordinate, check to see whether more subentries are needed at that level. In addition to dividing an existing topic, other solutions include finding additional topics for a branch with a single subentry or removing the branch and adding the single topic to another branch.
You can use emphasis and subordination to distinguish main points from supporting information. Users need a way to distinguish the highways from the back roads; they get lost when they can't keep track of the main points.
Emphasizing a main point involves one or more of the following techniques:
Placement
Placing topics or words first is the best way to emphasize a main point: in the heading or title, in the introduction, in the first sentence of a paragraph, in the first words of a sentence.
Introduction
An introduction, or overview, should announce to the user why subsequent information is important or how that information is relevant. Such an orientation places the subsequent information in context and thus makes it easier for users to learn or to understand the order of topics to come.
Repetition and reinforcement
Repetition keeps the user's mind on the point throughout the presentation. Effective reinforcement includes making a point in more than one way, such as by text and illustration, or by general statement and example.
Details
Details help emphasize what is important. Give users more details on important topics, and fewer details on topics that are less important.
The following paragraph seems to be about paragraphs at first, but it is actually about how to use markup tags:
Original
Users need to read the whole original paragraph to determine what the paragraph is about, and some users might not grasp the intended topic at all.
The first revised paragraph begins with the topic sentence. It uses repetition and contrast to emphasize the main point.
Second revision
The generalized markup tag identifies the kind of element that a portion of a document is, not the way that the element is to be formatted. For example:
Paragraphs are identified with a paragraph tag. They can be set to the left margin or indented under headings; they can be separated by one blank line, two blank lines, or none. But, in the source, they all begin with a paragraph tag.
A highlighted phrase is identified by a highlighting tag. It can be underlined when it is printed on one device, appear in italics when printed on another, and display in red in a window. It is still the same kind of element, a highlighted phrase.
Therefore, when marking a portion of a document, ask yourself, “What kind of element is this?” not “How do I want this to look?”
The second revision uses a list to set off the examples more clearly and make the information easier to scan. It also uses placement and reinforcement in the list items to keep the focus on the main point.
When you give unwarranted emphasis to secondary information, you make that information seem more important than it is. Though a minor point might belong in the text, elaboration of the point probably does not.
In the following passage, a note label is used to call attention to information that is no more pertinent than the other information in the passage:
Original
The original passage gives unnecessary emphasis to the statement about the benefits of canceling a registration. That statement is no more important than the other two statements, yet the note label gives users the impression that it must be more important.
Revision
In the revision, the information fits into the original paragraph without rewriting.
Note labels are a tempting method to use to insert new information into previously written topics. However, you'll soon find that your topics have a lot of notes and no flow and that users can't follow your main points. In addition, too many notes will dilute the effectiveness of the note label to visually emphasize a point. Take the time to fit the new information into the existing structure, or reorganize the information to accommodate the new information.
For information about visual emphasis, see the visual effectiveness guideline “Use visual elements for emphasis” on page 288.
When users first encounter a piece of information, they usually want to see it as part of a whole. Like travelers, they need a map both at the beginning of a journey and as their trip progresses to keep their bearings in relation to the destination.
For a book (whether online or printed), users rely on the following elements as a map: table of contents, headings, introductions or overviews, and transitions. In information centers, online help systems, and Web sites, users can keep their bearings with the following aids:
A navigation pane or site map
Overview topics that convey how subtopics are related
Transitions and links between topics that convey the relationship of one topic to another
A breadcrumb trail that lists the topics that a user has visited
Buttons that take users to the previous topic or to the next topic
The navigation pane or site map provides a map to those users who need a sense of the breadth of the set of information. However, because information centers, online help systems, and Web sites are not read linearly, you should provide overview topics that list related topics and show how those topics relate to each other. Users can return to these overview topics as necessary to link to other topics. In this way, users get a sense of the structure of the information and can read some of it linearly if they want to. Users also rely on effective transitions and links to convey the relationships of topics to one another.
All of these aids help users to verify their sense of the whole. If they can't verify it or if a piece doesn't fit, something is wrong or missing.
The following set of topics does not provide overview information for the tasks that are involved in using the sample program:
Original
The original set of topics includes a concept topic about the sample program followed by the task topics in the order that the user should do the tasks, a reference topic that lists the sample program files, and a task topic about removing the sample program. The user cannot tell from the navigation pane whether the order is important or how the tasks relate to each other. The overview concept topic in the right frame does not explain the relationships of the subtopics.
Revision
The revised set of topics includes an overview task topic that explains that the first four subtopics are all subtasks of the overview task and indicates the order in which to do them. The overview task topic provides information about the subtopic relationships that users cannot grasp from just the navigation pane alone.
Because topics are not always read linearly, you cannot assume that users have read topic A before reading topic B or that users who are reading topic A will know to go to topic B next. Therefore, introductions to tasks such as “Now that you have configured the receiver, you must configure the amplifier” are not sufficient. In the “Configuring the amplifier” topic, you need to mention that “Configuring the receiver” is a prerequisite task, and you need to provide a link to the “Configuring the receiver” topic. Do not assume that the user is reading linearly and has already read about configuring the receiver.
The same advice applies to other transitions between topics. Sentences such as “The next section explains how to configure the printer driver” assume that the user sees the sections in a certain order. A better way of mentioning a follow-on task might be to provide the following sentence in your topic: “After you complete this task, you must configure the printer driver.”
The following passage shows the end of a topic that explains how to install a product:
Original
The original topic ends as soon as the installation process is started and doesn't point the users to the next place to go in the set of information. The users must figure out what to do next, if anything.
Revision
The revised topic explains to users that they can now configure their system. The link to the related task is provided at the end of the topic for users who want to go to the next task.
Because users do not read information centers, online help systems, and Web sites linearly, users need to understand where they are in the set of information and where they can go. Navigation panes provide a hierarchical view of the structure of the set of information. Overview topics and transitions are valuable supplements to navigation panes because they help users understand where they are and what to do next. In addition, users rely on breadcrumb trails to help them return to overview pages so that they can take other links and explore without getting lost.
See the retrievability guideline “Facilitate navigation and search” on page 247 for more aids that you can use to help users keep their bearings.
Organization deals with much more than how you arrange your topics. Well-organized information never leaves the user feeling lost. The order of tasks is clear, transitions suggest follow-on tasks and lead the user in the right direction, topics are easy to find, topic content is arranged for quick retrieval, contextual information is not hidden, and the overall structure is always available to the user.
When you review technical information for organization, you can use the checklist on page 244 in two ways:
As a reminder of what to look for, to ensure a thorough review
As an evaluation tool, to determine the quality of the information
Based on the number and severity of items that you find, decide how the information rates on each guideline for this quality characteristic. You can then add your findings to “Quality checklist” on page 387, which covers all the quality characteristics.
Although the guidelines are intended to cover all areas for this quality characteristic, you might find additional items to add to the list for a guideline.
