21.  Revising a Document.     

We talked about revision in unit 4. Editing seems to end only when you relinquish control of the document.  So we will talk about it some more.  The following tables illustrate editor's copy marking symbols.  Obviously these are meant to be written on a paper copy.   It is easier, quicker, and less ambiguous for an editor to simply make changes and save the document as a variant; instead of "text.doc," save it as "text1.doc."  However, my textbooks tell me this should not be done.  One says: "To make these changes silently is wrong both ethically and practically.  Would you want someone changing your text without telling you?"  I agree that an editor should "tell" the writer what changes he has made.  By making the changes, instead of copy marking, an editor puts the burden on the writer to find the differences or corrections.  Since the changes are already made by a person who is often your superior, it may be politically difficult to restore your version.  Using a 21-inch monitor (and bifocals) I don't find it difficult to open the 2 files side-by-side and read them alternatively to see changes.  It is true that on-line editing makes it difficult to get a visual and organizational sense of the entire document or even large parts of it.  Consequently, you will want to print a draft/s at some stage of editing.
Instead of making changes, many editors prefer to "suggest" changes in all boldface, underlined, [placed in brackets, with font changed to Arial narrow], with bars or "i" before and after the changes: |change| or i change i.  Deletions may be indicated by strikeouts: delete.  You do that by opening "format," selecting "font" and clicking on "strikethrough."

Here is another version:

Steps in Document Production

1.  Is a Document Needed?

• Authorization. 
• Initial planning meeting/s.
• Specify the type/s of documents.
• Establish: team, deadline, budget, preliminary assignments. 

2.  What kind of document? 

• Print media or on-line?
• Assess purpose, audience, and scope (initial requests for facilities, equipment, personnel, time and other resources).
• Sketch the overall design.

3.  What kind of data?

• Identify sources of data.
• Identify and employ methods to gather data.

4.  Document Drafts

• Develop organization pattern/s.
• Determine document and page design (specify programs such as PageMaker, FrameMaker, or MS Word to produce  uniform document types (.doc, rft, pdf).
• Design, develop and integrate visuals; tables, graphs, charts, illustrations, and "eye candy."
• Write the 1st draft.
• Revise the draft (author or team).

5.  Revise and Evaluate 

• Submit for reviews.
• Run usability or pilot tests.
• Seek audience reaction (including observation).

6.  Edit

• Determine the level or type of edit/s. 
• Perform edit/s.

7.  Document Production

• Typeset, proofread, print, bind, distribute, evaluate.
• Upload to Website, test graphics, links, and appearance in multiple browsers. 

Types of Editing:

The Organization Edit: 

• Analyze the document for major conceptual components identifiable from the table of contents.  
• Are the headings "stock plan" (introduction, recommendations, findings) or content specific?  How many levels of division?  Are there enough divisions or too many?  
• For audience defined documents (requests for proposals, resumes, journal articles), check to see that the typical or specified parts are there.  The easiest thing to cut on the first round of reading proposals or job applications or even journal submissions are those that lack specified components or otherwise do not follow directions.

Content Edit: 
Checklist for assessing conceptual content:

• Why was the document written?  Who authorized it?  What does it seek to accomplish?
• Is the title too general (vague) or too long?
• Is the informative abstract correctly done?  This usually means devoting a sentence to each of the first order divisions in the table of contents and checking to insure that data is reported.  Many writers lapse into a descriptive abstract: "the authors used a new technique to produce four findings and two recommendations."  So tell us the methods, the findings, and the recommendations!  Remember that the abstract will literally have hundreds of times more readers than the document and that the abstract is a kind of advertisement for the report.  Consequently, you should make the abstract intelligible to a broader group of readers than the report itself.  Check to see that the abstract is "stand alone" intelligible.  It cannot make references to parts of the report. 
• Is there a purpose statement in the 1st or 2nd paragraph?  Does the introduction provide enough context or background for all readers to grasp the significance or scope of the report?  This is a frequent flaw.  Writers often begin in the middle, too minutely describing parts or processes without explaining how they fit into larger mechanisms or processes.
• Audience analysis.  Does the document clearly define target audience/s?  How?
• Are visuals appropriate to the audience level?  Does each pass the "stand alone" intelligibility test?  Are there enough or too many for the target audience?  Manuals that target 8th grade readers may wish to use visuals to convey 70% or more of the information.  Research papers for a Ph.D. audience may use prose to explain graphs, tables, or equations that are the essence of the paper.  Scientific American sets a standard for both adapting technical content for a general academic readership and for paralleling discursive information with great visuals.
• Is the organization coherent and the development logical?  Are facts, details, and examples unified to illustrate the division under the heading?
• Is there a consistent and visually intelligible method of organization that is used consistently and accurately?
• Are divisions logical components of major headings or more inclusive headings?
• Is each section or step of a process discrete, logical, and accurate?  Testing and observation are usually required to answer these questions.
• Does each section of step logically follow from the previous one?
• Check for errors of fact, policy, or security.
• Does the text (explanation, illustration, instruction) support the recommendations?  
• Are facts and details properly partitioned under appropriate "user friendly" or audience driven headings?  It is easy for a writer to stray from the formula for recommendations (who, what, when) to begin to explain the rationale for a recommendation (why) or methods of implementing a recommendation (how) -- information that should be located under more accurate headings.
• Are there topics mentioned or implied in the introduction that are not developed?  Obvious reader questions cannot be ignored.  You must acknowledge them even if you do not have answers.
• Does the raw data or analysis of findings imply ideas, applications, or cautions that the document fails to explicate?

You can add to this list.  These are concerns or questions that most thoughtful and interested readers would implicitly have in mind when reading your document.  These concerns are conceptual and organizational, not the rather picky concerns of presentation and grammar.

Copy Edit: 
Now we get picky.

Paragraphs

• Each paragraph has an identifiable topic sentence.
• Each paragraph is unified to develop the idea expressed in the topic sentence.
• Each paragraph is long enough to adequately develop the topic sentence and/or provide adequate support and illustration.
• Clear and logical transitions between paragraphs.  Explicit organization by headlines and the decimal outline system may obviate the need for discursive transitions. 

Sentences

• Each is complete or there is a rhetorical reason for fragments.
• Each clause has an identifiable subject.
• Subordination makes secondary concepts clearly related to the primary one.
• Coordinated ideas are properly expressed in parallel phrases, clauses, or elements.
• Active voice: most sentences follow the subject-verb-object pattern.
• Complex ideas are explained in simple, clear sentences.
• Some variation to avoid robotic monotony of style.
• Expletives (it is, there are) at the beginning of sentences are minimal. 

Transitions

• There are transitions between sections, paragraphs, and sentences.
• The transitions are both explicit in the decimal outline or headlines and expressed discursively to clarify the conceptual development (e.g., "the second concern in making the incision is . . . .").

Voice

• The active voice is used to identify those who perform the described action or to otherwise achieve clarity and avoid ambiguity and awkwardness.
• When the passive voice is used, you have made a decision to use it.
• Voice should be consistent and not the result of an unconscious shift within sentences, paragraphs, or sections.

Point of view

• When the author is a participant or observer, write from the 1st person point of view.
• When the text uses the imperative mood (to give directions or instructions), write in the 2nd person point of view.
• With the impersonal point of view, try to change to a more natural point of view when possible.  Documents that go on page after page in the impersonal point of view are hard to follow.
• Is the author careful to separate and identify various points of view:
  • "Management believes . . . " 
  • "I think . . ."
  • Are personal judgments supported by cited authorities?
• The author should avoid self-references made in the third person or by improperly using reflexive pronouns.
• Is the point of view consistent?
• For "boiler plate" documents assembled from the work of multiple authors, the point of view should be consistent within the section, even if it shifts between sections.
• Do pronouns have clear antecedents; do they grammatically agree with the antecedent?

Parallelism

• Parallel structures contain logically uniform parts.  Are the elements alike in grammar and function in:
  • Phrases, clauses, series.
  • Lists in tables.
  • Between the table of contents and topic headings.
  • Among a series of topic heading (usually 2nd order or lower).

Consistency

• Terms should be uniform or consistent.  Avoid ambiguous synonyms for technical terms, if there are such synonyms.  If you refer to the same idea or item using more than one term, clearly identify the synonym parenthetically and perhaps in a glossary.
• Abbreviations, acronyms, and symbols should be those specified by professional reference works that define standards of use.  Internal documents that use locally defined acronyms should be questioned.  Are you sure every reader understands the acronym?  How hard is it to parenthetically define acronyms after the first use?
• Verb tenses remain consistent without gratuitous or unconscious shifts.

Word Choice / Diction Level

• Terminology and jargon match the target audience.
• Stipulatory use is recognized so that there is no confusion between commonly used terms that have a stipulated or special definition in some technical fields.  I previously mentioned the easily misinterpreted meaning of Tera: terminal effects research and analysis.  "Terminal effects" means very different things to the health care community, to botany, and to weapons science.
• Does the author exhibit audience analytic care by stipulating such definitions?
• Would a glossary help?
• Avoid nonstandard English usage ("ain't," "irregardless," "we didn't get none").
• Do illustrations and descriptions adequately explicate connotations and implications?
• Sexist language.

Wordiness

• Repetition in various sections can enhance understanding, create emphasis, and make references clear and simple. 
• Within paragraphs, authors can strain too much to rename the same thing unnecessarily or awkwardly.
• The same problem can exist with visuals.  Complex graphics may need serial development.  Like prose, graphics should be audience specific.  Academic research articles may require difficult tables and conceptual illustration.  Conversely, simple but lengthy instructions can be made more readable when they are broken up with entertaining, but not conceptually significant, illustration. 
• Nominalization:
  • Weak: A winglet may cause the introduction of a discontinuity in the lift distribution curve.
  • Better: A winglet may introduce a discontinuity . . . .
  • Weak: Regeneration of the resin bed is achieved by a calcium chloride solution.
  • Better: The resin bed is regenerated by a calcium chloride solution.

Punctuation

• Standard rather than idiosyncratic, e.g.,  gratuitous capitalization. 

Graphics

• Could parts of the text be enhanced by appropriate illustration?  Text can be replaced or effectively repeated by using tables.
• Graphics may reduce the readability index, making the document more accessible to multiple readers.
• Are figures and tables correctly labeled and rendered; are they independently intelligible?
• Are visuals correctly proximate to the explicit reference?  "See figure one" should not cause the reader to thumb through the document to find it.
• Does the text parallel and/or explain graphics?
• Are terms used consistently in tables, graphs, headlines, and text?

Style Edit: 
This is the last chance you have to catch errors.  Some of your concerns should be: 

Text Elements

• The sections and subsections are there and in the correct sequence, including the abstract.
• Cross-references are accurate, especially those that refer to page, figure, and table numbers.
• Entries in glossaries, indexes, and lists of symbols and acronyms are in correct alphabetical sequence.
• Lists of tables and/or figures match the sequence in the text.
• Page numbers in the lists of tables and figures are accurate.
• Each heading in the table of contents matches, word for word, the headings in the text.
• Page numbers in the table of contents are accurate.
• Page numbers in the index are accurate.

Graphics and Tables

• Graphics and tables are present, the right ones, and in correct sequence.
• Each has the proper number and a stand-alone caption.
• Every graph must have the table of figures used to make the graph.
• Check the scale or grid of graphs so that interpolation to degrees of accuracy greater than the tabular data is not possible.
• Graphs start with a true, rather than suppressed, zero.
• Borrowed figures are cited or credited.
• Callouts or caution boxes are accurate, legible, and intelligible.
• Copyright and security concerns.

Lists

• Lists are consistently formatted:
  • Consistent margins: indented, flush left.
  • Bullets, numbers, letters.
  • Consistent capitalization and end punctuation (none, semicolon, period).

Equations

• Numbered in sequence.
• Symbols and numbers are consistent in type style and size.
• Exponentials (power-of-10) notations are formatted consistently in text and tables.
• Adequate white space around equations.
• Multi-line equations break at operational signs, parentheses, or brackets.

References / Appendix

• Bibliographic references are complete and accurate in detail.
• Entries are consistent in style and alphabetical.
• Web sources and interviews correctly cited.
• All data collected is present in the appendix or adequately referenced so that it could be retrieved.

Typography

• Size and style of typefaces or fonts are consistent throughout: text, headings, footnotes, figure captions.  What you see is not always what you get.  When composing html documents, the font type may revert to "default font" when you click the mouse to move the cursor several lines.  The font you see on your monitor may remain, for example, Times New Roman because that is your default font.  Someone else's computer may be set to Arial or some other font as the default.  Your page is likely to display in a motley of the two text fonts.
• Page backgrounds for Web documents can also surprise you.  You set your browser to display a white background and leave the page setting in FrontPage to "automatic," which means that the page background will display the default color selected by the user.  If you use white background graphics, they look seamless on your monitor, because you set the background to white .  The guy who has a beige or peach or mint green background sees a lot of white postage stamp images.  Make sure you adjust "page properties" to select a white background (if that is how you want your pages to look).  In FrontPage, right click with cursor anywhere on the document page.  Select "page properties" from the menu.  Select "background" from the tabs.  Look for "Color" and "Background."  Click on the color box and select. You can also globally choose a color other than black for the text (Most of this text is navy blue).
• Number of text columns on a page.
• Height and width of each column.
• Ragged or justified margins.
• Size of all margins.
• Location of headers, footers, page numbers.
• Placement and size of graphics.  The size of graphics is easy to control in html documents.  When you "borrow" images, think about graphically editing them.  Reduce the size.  Crop irrelevant parts.
• Positioning of tables, graphs, lists.

Of course this is not a complete list.

Back to navigation