Documentation Home Page
Designing Readable Documents
Planning Ahead
Organizing the Content
Writing Clear Sentences
Writing Computer Instructions
Using Tables & Graphics
Paying Attention to Typography
Checking Spelling and Grammar
Checklist for Readable Documents
Computer Conventions Overview
Further Reading
Technical Writing Glossary
IT Services Home
Support Desk
MU Knowledge Base
Home
Search
Contacts
News
Sports & Events
Designing Readable Documents
 


Topic 2: Organizing the Content

People are often very busy (do you recognize this?) and they don't always take the time to read every sentence of your document. Despite the fact that it has taken you more than an hour to write a memo or executive summary, the person reading it might skim it in two minutes. To make sure people get the most out of your document as possible, you will need to organize your text in a logical way.

In this topic you will learn some techniques to improve your document in such a way that readers are able to pick up the important information quickly, and also will be able to remember what they read. One way of doing that is using a forecasting statement, like the following sentence:

In this topic we will discuss the following five ways to improve the organization of your document:

Get to the point and forecast what is going to happen

Don't let your reader wonder what your document is about. Use an overview or a forecasting statement to inform the reader what is coming. An overview can inform readers whether your document is what they want. It will also prepare them for understanding what is to come. A forecasting statement can have the same effect. Look at the following example.

EXAMPLE
There are three ways of attacking this problem. First you can look at the Knowledge Base. If that doesn't solve your problem you can call the Support Desk. A third option is to reset your computer and hope that it works.

In this example the writer uses a forecasting statement; the writer announces that there are three ways to attack the problem. Research has pointed out that readers need something "to hang the information on." If the reader knows in advance that you are going to describe three different things, he or she has a way of storing that information.

Chunk complex content

Nobody likes reading endless pages of text. Cut the text into small chunks of information and use different level headings to illustrate the organization of your text. Use informative headings, rather than general ones, such as "Introduction," or "Results."

When you are using Microsoft Word you can use the Outline View to organize your content:

    1. Go to the View menu and click "Outline". In this view you can decide how many headings you want to see.
    2. Click on "1" or "2" for only level 1 or 2 headings, or click ‘all’ to see the entire text.
    3. Compare, for instance, all the level 2 headings and see if they are parallel and in the right order.
    4. You can easily change the order of the paragraphs in Outline View by dragging and dropping the headings.

Chunk complex content and use forecasting statements.

Reduce abstractions and complexity, use examples and analogies

Abstract writing is so general that readers constantly have to guess what it means. For example: "As an IT consultant, I sometimes find strange things. "Things" can refer to many different situations or items, and a reader just has to guess what the writer meant. Abstract sentences are easily forgotten. Concrete examples will make people remember what you said.

EXAMPLE
As an IT consultant, I sometimes find strange things. Once I was with a client who complained his computer made strange noises. When I opened up the computer case a small mouse jumped out of it.

In this example the abstract sentence was explained by giving a concrete example. You can also use analogies or metaphors when appropriate to lessen complexity.

A well known example of a metaphor is the use of the terms "desktop" and "folder."

Order your content within paragraphs

A paragraph should only discuss one general topic. And within that paragraph, put individual items, sentences and paragraphs in a logical sequence. Good organization results in readability cues being available for the reader.

  • Put the most important or widely used information at the beginning of the entry.
  • Put the general before the specific.
  • Describe a sequence logically and step-by-step.
  • EXAMPLE
    This paragraph from the introduction to the MUnet guide is a good example of a structured paragraph where the general is put before the specific. The topic line is explained by two examples in the text.

1. Access to information continues to improve.

1. Topic sentence.

2. Library resources link our campuses to the world of information.

2. 1st example of the statement in the topic sentence.

3. Increasingly, Miami's own instructional and administrative information is being made available and used electronically both within and beyond our University.

3. 2nd example.

4. For several years, our electronic Directory (PHonebook) has made it easy to find anyone currently affiliated with the University—students, faculty and staff—excluding those who request omission for privacy or safety reasons.

4. Expansion of 2nd example.

5. Students have been able to consult course scheduling information in real time. This year it is easier than ever for professors to make course content available to their students through Blackboard CourseInfo. Soon students, faculty and staff will be routinely accessing most University administrative information services through a web interface.

5. Expansion of 2nd example.

6. As always, these and other services are linked through Miami's institutional web site at http://www.muohio.edu/

6. Conclusion, this sentence integrates al former examples and refers back to the topic line.


Place sentences in a logical order.

Put the general before the specific.

Use bulleted or numbered lists

Lists are really useful to present your information. They can give an overview and create easy comparison among the items. Don't use too many lists, however. Using too many lists can create the sense of reading an outline rather than the finished text.

Something to keep in mind if you use lists:

  • Use a bulleted list when there is no preferred sequence.
  • Use a numbered list only when the order of the list items is important, for example in a step-by-step procedure.
  • Try not to use more than seven bullets or steps in a list or procedure. Research has pointed out that seven is the maximum number of items people can oversee at once.
  • If there are more than seven items, think of grouping them and using subheadings.

Also make sure that the list items have a parallel structure. In the following example it is correct to use a bulleted list because there is no preferred sequence of the list items. The entries of the list, however, are not parallel.

Poor bulleted list:
There are several ways to open documents in Windows. You can:

  • Open your document from within the program you used to create it.
  • Use the Documents command on the Start menu.
  • The Find command on the Start menu locates the document and you can then open it.
  • Double-clicking a document icon in My Computer opens a document.

Reorganize a list with more than seven items.



Please send comments and suggestions to IT Services Learning and Information Services (LIS)