3. DOCUMENT DESIGN
Anything that you write is designed to be read. That is its first and foremost purpose. Thus, increasing readability means increasing the functionality of your document in terms of both content and document design—making it “user friendly.” If your document is difficult to read because vocabulary, sentence structure, paragraphing, organization, or formatting is unclear, your reader will likely stop reading.
The Revision Checklist below offers a step-by-step process for revising your document to achieve a readable style. It incorporates key information from Chapter 2: Professional Style and Chapter 3: Document Design. Implementing this checklist means doing several “passes” over your document, looking at different aspects each time. For example, in your “first pass,” review the entire document for overall formatting, content requirements, coherent flow of information, and appropriate tone.
1. First Pass: Document-level Review
- Review specifications to ensure that you have included all required content.
- Make sure your title, headings, subheading, and table/figure labels are clear and descriptive. Headings should clearly and efficiently indicate the content of that section; Figure and Table captions should clearly describe the content of the visual.
- Make sure visual elements have appropriate passive space around them.
- Make sure ideas flow in a logical order and explanations come in a timely manner. Make sure visuals illustrate your textual information.
- Write “Reader-Centred” prose: determine the relationship between your purpose in writing and your reader’s purpose in reading. Give your readers the information they want and need to get from your document as efficiently as possible.
- Make sure you are using an appropriate tone (neutral, objective, constructive, formal)
2. Second Pass: Paragraph-level Review
- Make sure each paragraph begins with a topic sentence that previews and/or summarizes the content to come.
- Add coherent transitions to link one sentence logically to the next.
- Cut unnecessary or irrelevant information.
- Avoid overly long or short paragraphs (5-10 lines long is a reasonable guideline).
3. Third Pass: Sentence-level Review
- Watch sentence length; consider revising sentences longer than 25 words. Vary the length and structure of sentences.
- Look at the ratio of verbs:number of words per sentence. Generally, the more verbs/words in the sentence, the better the sentence.
- Use concrete, strong, active verbs – avoid vague, passive, verbs and “is/are/was/were/being” whenever feasible (move the –tion and –ment words up the verb scale).
- Create a clear Actor/Action relationship (Subject-Verb).
- Verbs like “make” “do” ‘have” and “get” have many possible meanings. Try to find more precise ones.
- In general, keep subject and verb close together, and keep verb near the beginning of the sentence.
4. Fourth Pass: Word-level Review
- Use concrete, specific, precise words; avoid vague, abstract, generalizing words.
- Match your vocabulary to your audience: experts can tolerate complex information with a lot of terminology; general readers require simpler, less detailed descriptions/explanations.
- Use clear, plain language rather than pompous diction; write to express, not impress.
- Avoid “sound bite” phrases that have no real meaning; use a single word instead of a phrase whenever possible.
- Avoid clichés, colloquial expressions, and slang.
- Use second person (you) pronouns carefully and sparingly.
- Avoid “ad speak” — don’t sound like you are “selling” something; use objective, measurable descriptors.
If your document incorporates sources, you will want to do an additional “pass” to make sure that all sources are cited properly and in chronological order in the body text, and that they all cross-reference to your list of references at the end of the document. See Chapter 6: Citing and Documenting in IEEE Style for details.