Revise & Finalize the Document

Revise and finalize your document based on feedback, if possible, as other readers/users can usually point out places where they experienced confusion or needed different information presented differently.

Know, also, that revision itself is a mini-process in the overall process of document design. As you revise, always move from big to small. That is, deal with content and structure first—the ideas and the logic of their presentation. You need to make sure that you have appropriate content in an appropriate order before you deal with the way in which that content is presented through graphics and language. Note that calling graphics and language “smaller” is not intended to diminish their importance. It’s simply that dealing with these items is in the nature of fine-tuning, while dealing with content and structure is re-thinking.

Other sections of this text deal with document content, structure, appearance, and language. You may want to consult those pages for fuller information. This page condenses information about these technical writing aspects in order to present a brief, yet comprehensive explanation of how to revise.
Revision may at first seem overwhelming, but you’ll fall into a pattern and it will become more natural, especially if you revise from big to small, from content and structure to look and language. Nonprofessionals often question why professional writers and editors insist on bothering with such seemingly picky, trivial, petty details in writing—but they all add up. It’s the accumulation of little issues in these areas—even seemingly trivial issues—that make a document difficult to read and understand. Your goal in revision is to create the clearest document possible for your purpose and audience.

Revision Techniques: Content & Structure

Content

One of the most important ways you can review a rough draft is to check its contents for informational value. All the good organization and clear sentence structure in the world can’t help a technical document that doesn’t have the right information for its audience. After you get feedback and/or set the draft aside for a while, revise for the following:

  • Information is missing. For example, if you wrote a technical report on “virtual communities,” but never bothered to define what “virtual community” means, you need to add that definition so your reader knows precisely what you’re talking about.
  • Information is there, but not enough. Using the same example, if you only made a general statement about virtual communities, you may need to add more information that specifies, defines, or describes virtual communities so your reader understands. Also, consider examples and analogies (comparisons) when you need to add information.
  • Information is there, but at the wrong level for the audience. If you included a two-page explanation of virtual communities using highly technical information, in a document intended for a non-specialist audience, you need to revise to match the readers’ knowledge, background, and needs.
  • Information is there, but not exactly right for the document’s purpose. If you included instructions on how to start a virtual community, when your purpose in the technical report was to explain how virtual communities function and what issues they might encounter, then you need to edit out the instructional information irrelevant to your purpose. You may need to review the remaining information to make sure that what remains is enough to address your purpose.

Always start the revision process by revisiting how the document’s information addresses your audience and purpose.

Structure

Once you’ve determined that you have audience- and purpose-appropriate information in a technical document, move on to review structure. Check to determine that your information is clearly and sufficiently organized, via paragraphs, sequence of those paragraphs, and level of information.

Paragraphs

In technical writing, paragraphs indicate a shift in topic or subtopic, or some shift in the way a topic is being discussed (e.g., a move from explaining a concept into examples that illustrate the concept). Revise your rough draft at the structural level by checking for paragraph breaks. Make sure that you have a clear paragraph for each main idea, topic, or section of a document. If you have a lot of information in a big paragraph on a topic, you may need to break up information into smaller paragraphs within the discussion of that topic.

Understand that paragraph length in written documents is dictated by content. Make sure that each paragraph contains a clear point, clear purpose, or single theme. According to The Writing Center at the University of North Carolina, Chapel Hill, “the unity and coherence of ideas among sentences is what constitutes a paragraph.” [1]

Paragraph Sequence

Sequence refers to the overall order of information that you have chosen to use. The order of information in a document needs to be logical for that document’s purpose, audience, and type. For example, most explanations of process use a chronological order; readers might not understand how to do something if you ordered instructional information from least to most important steps. When you revise, make sure you order paragraphs in an appropriate sequence.

Level of Information

Level refers to the level of specificity of information and the way general and specific information is ordered within a paragraph and sometimes within the whole document as well. Usually, you place general information first to create a conceptual “framework” so that readers can then understand the more specific information. When you revise, make sure you’ve applied a general-to-specific organization as appropriate. The general-to-specific order applies to concepts and their explanations within a document, even when the whole document uses a different overall sequence of information.

Paragraph revision for general-to-specific organization, within an overall document whose purpose is to describe
Problem version Revised version
There are various types of solar collectors; however the flat-plate solar collector is currently the most common and will be the focus of discussion here. The most important part of a solar heating system is the solar collector whose function is to heat circulating water necessary for space heating. A typical solar collector has layers of glass with intervening air spaces to produce a heat-trapping effect. Most solar collectors consist of a black absorber plate covered by one or more of these transparent cover plates made either of glass or plastic with the sides and the bottom of the collector insulated. The most important part of a solar heating system is the solar collector whose function is to heat circulating water necessary for space heating. There are various types of solar collectors; however, the flat-plate solar collector is currently the most common and will be the focus of discussion here. A typical flat-plate solar collector has layers of glass with intervening air spaces to produce a heat-trapping effect. Most solar collectors consist of a black absorber plate covered by one or more of these transparent cover plates made either of glass or plastic with the sides and the bottom of the collector insulated.

Revision Techniques: Look & Language

Document Appearance

The look of a document influences how a reader will interact with it. As you revise, consider the following elements that contribute to the document’s appearance.

Paragraph Length

Paragraphs in most technical documents are relatively short (e.g., 6-8 sentences). A page in a written document usually contains a few paragraphs. While there’s no standard paragraph length, since paragraphs have different topics and purposes, err more toward brevity than length so that readers see breaks and will not be turned off by a wall of dense text.

Note that paragraphs for online pages tend to be very short, as research shows that online readers tend toward scanning as opposed to reading fully. And paragraphs for fuller reports, often intended for expert reading audiences, tend to be fuller in order to present more complex information.

You can also shorten your sentences if you decide you need to shorten paragraphs, in addition to breaking up longer paragraphs. Remove unnecessary words. Condense two sentences into one if that makes sense. Don’t say things twice if once will suffice. Be as concise in wording as possible, while still including the information your reader needs, in order to create a sleeker, easier-to-read document.

Headings & Subheadings

Since readers can be intimidated by big blocks of text, search for places to incorporate headings as appropriate when you revise. While headings may not be necessary for very short documents, they are important for most other documents, as they break up the text and, along with topic sentences, serve as signposts for your content. Headings allow readers to preview a text and get a sense of its content and purpose. They also help readers find or re-find the exact information they’re looking for.

Graphics

As you revise, consider whether you have used graphics appropriately for your purpose and audience. Are the graphics clear, easy to understand, and relevant to concepts in the text? Do you need more or different graphics to clearly illustrate a concept? Or can you eliminate graphics given your purpose and audience? Do you have graphics that are more decorative, not truly necessary to a reader’s understanding of content? If so, should decorative graphics stay or not, to break up a text and get a reader to engage with your content? These are the kinds of questions you should consider about graphics when revising.

In general, you may want to use more and/or simpler graphics for non-specialist audiences. Graphics for specialists may be more detailed and technical.

Layout & Formatting

Is there enough white space (blank space, as in margins and spaces between sections) so that your document is easy to read? Is the type large enough to read easily? Have you used a clear and appropriate type font? Also, have you followed conventions for layout and formatting if you’re writing a technical document that traditionally has certain conventions?  (e.g., proposals often have sections such as Problem, Possible Solution, and Proposed Solution)

Language

Here’s a short sentence that offers a key concept: Review language to make sure it’s correct and clear.

To revise language, find and revise the following key items (among others – that’s where feedback helps):

  • errors in grammar, punctuation, and spelling – use a spell-checker, but realize that it will not always catch wrong words
  • excessive or redundant words – cut down on words
  • “of” constructions if they are awkward or abundant – rephrase without “of”
  • passive voice verbs – change to active voice as appropriate
  • sentence structures – favor simple subject-verb structures over complicated sentences
  • repetitive sentence structures – vary your sentence patterns

Final Revision: Constraints

As a final piece of revision, once you have dealt with content, structure, look, and language, make sure you’re following the style expected by the company or group for which you’re writing, applying the limits or constraints that the company or industry sets. Companies and industries may have expectations, regulations, or other factors that may constrain what you can say and how you can say it, regarding tone of voice, use of abbreviations, tables, margins, maximum document length, and any of a number of style or format items.

Since all documents can be used against individuals and companies in court, all written documents with the company name should include only professional content that properly represents the company, in the way that company expects to be represented. Writing constraints can also originate outside of a company. For example, government regulations specify how patent applications, environmental impact reports, and many other types of government documents are to be prepared. Similarly, scientific, technical, or other professional journals have strict rules about many aspects of the articles they publish.

So make sure that you apply relevant style expectations as a final step in the revision process.

[1] Paragraphs. The Writing Center, University of North Carolina at Chapel Hill. https://writingcenter.unc.edu/tips-and-tools/paragraphs/