Editing
(1) The reader should be able to find out what the story is about. (2) Some inkling of the general idea should be apparent in the first five hundred words. (3) If the writer has decided to change the name of the protagonist from Ketcham to McTavish, Ketcham should not keep bobbing
up in the last five pages.
James Thurber's standing rules for writing of humour
What's so funny?
If a conscientious reader finds a passage unclear, it has to
be rewritten. Karl Popper Unended Quest
The writing of a paper begins with a rough draft, perhaps based on notes of experiments or sketches of a couple of theorems. The next phase is usually of filling out the draft to form a contiguous whole: explaining concepts, adding background material, arranging the structure to give a logical flow of ideas. Finally, the paper is polished by correcting mistakes, improving written expression, and taking care of layout. Although it does not change the quality of the research, it is this last phase—the styling of the paper—that has the most impact on a reader. It should not be neglected however strong the ideas being communicated.
Editing
Consistency
123
Style
Editing is the process of making a document ready for publication. Much of editing consists of checking the document for errors that fall under the heading of consistency (or lack of it). Use the checklist starting on page 126 when revising your papers, or when proofreading papers for others. A surprisingly effective editing exercise is to pretend to be a reader, a member of the paper's intended audience. This shift of framework—of consciously adopting the pose of external critic—often exposes problems that would otherwise go unnoticed.
My experience is that early drafts tend to be repetitive and long-winded. Often, not only are concepts awkwardly expressed and sentences unwieldy, but material on one theme might be in several separate parts of the paper. It is common to find similar material included several times, particularly when there are several authors. Another problem is that some material becomes irrelevant as the paper evolves.
The ordering too may need to be reconsidered once the paper is complete. When material is moved from one location to another, check that the text in each location is both intelligible and appropriate in the new context. Beware, for example, of moving definitions of terms or of breaking the flow of an argument.
For many papers, then, editing results in excision of text. Don't be afraid to shorten your papers: cutting will improve the quality. Edit for brevity and balance. Omit or condense any material whose content or relevance to the paper's main themes does not justify its length.
Another kind of editing is for style and clarity, and is perhaps the hardest part of finishing a paper. Much of this book is concerned with points of style that should be checked during editing; these should be considered during every revision. Keep in mind the basic aim: to make the paper clear. Lapses will be forgiven so long as you are easy to understand.
When revising the text of other writers, it is often preferable to make minimal changes: correct the presentation but retain the flavour of the original text. Don't expect to impose your style on someone else.
Most journals have a preferred style for references, figure numbering, spelling, table layout, capitalization, and so on. If you are planning to submit to a particular journal, consider using its style.
24
Writing for Computer Science
Editing
125
Proofreading
There no excuse for a report that contains spelling errors. They jump out and glare, displaying not only your inability to spell, but also your casual attitude to your work. Find a spelling checker that you like and get into the habit of using it. But spelling checkers won't find missing words, repeated words, misused words, or double stops. Nor will they find misspellings that form another correct word; a typical example is the substitution of "or" for "on" or "of". (Another example is from a newspaper article about a couple who, in their wedding ceremony, "stood, faced the floral setting, and exchanged cows".) Adopt a convenient set of symbols for correcting proofs; many dictionaries and style guides have good examples of notation for copy-editing.
A common error of mine is, when intending to type a word, to instead type some other word that shares a few initial letters. A related error is that I replace words by their anagrams. Undoubtably there are a few of these errors in this book—they are hard to find. (One draft of the previous sentence began "Undoubtably there are few of these errors ... ")
Identify and look for your own common errors. Typical examples include incomplete sentences and sentences that have been run together inappropriately. Check for errors in tense and in number, that is, in the use of plural and singular forms. Remember that a plural noun can require a differently-formed verb to that required by a singular noun. For example, "a parser checks syntax" whereas "compilers check programs".
Examining your document in a text editor is no substitute for reading it on paper after it has been formatted. It is vital to read it at least once in its entirety, to check flow and consistency. Set the article aside for a day or two before proofreading it yourself—this increases the likelihood of finding mistakes.11  (Many people have an emotional attachment to
vith their short deadlines, inevitably overlook some mistakes. The following is the complete text of a newspaper article (as quoted in the New Yorker).
The Soviet Union has welded a massive naval force "far beyond the needs of defence of the Soviet sea frontiers", and is beefing up its armada with a powerful new nuclear-powered aircraft carrier and two giant battle cruisers, the authorative "Jane's Fighting Ships" reported Thursday. "The Soviet navy at the start of the 1980s is truly a formidable force", said the usually-truly is a unique formidable is too smoothy as the usually are lenience on truly a formidable Thursday's naives is frames analysis of the world's annual reference work, said the first frames of the worlds' navies in its 1980-81 edition.
"The Soviet navy at the start usually-repair-led Capt. John Moore, a retired
their writing; the delay allows this attachment to fade.) It is particularly important to check the bibliography. Readers will use it to track down references, so any garbling of information can lead them astray, and other writers may be offended if you have misreferenced their papers. Format should be consistent and each reference should include enough information to allow readers to locate it.
Always get someone else to read your work before you submit it or distribute it. You may have misunderstood a relevant article, or made a logical error; most authors are poor at detecting ambiguity in their own text; there may be relevant articles or results of which you are unaware; explanations may be too concise for the uninitiated; and a proof that is obvious to you may be obscure to others. And a proofreader's comments should never be ignored. If something has been misunderstood, the article needs to be changed, although not necessarily in the way the proofreader recommends.
Publication-quality word-processing is so widely used that poorly presented reports look cheap. But word-processors, no matter how good, can glitch on the final draft. The last word of a section might be the first word on a page, a line of text might be isolated between two tables, or a formula might be broken across two pages. This is also the last chance to correct bad line breaks. Some editing may be required to fix such errors, to move or change the offending text or to relocate a table. In desperate cases, such as a long piece of displayed mathematics that is broken, consider putting the offending material into a figure.
Fussy people like me clean up widows and orphans. If the last line of a paragraph contains only a single, short word, that line is a widow; use an unbreakable space to join the short word onto the previous one.
British Royal News Services.
"The Soviet navy as the navy of the struggle started", she reportable Thursday.
"The Soviet navy at the start of the 1980s is truly a formidable force", said beef carry on the adults of defence block identical analysis 1980s is truly formidable force, said the usually-reliable of the 1980s is unusually reliable, lake his off the world's reported Thursday.
The following is from an article in a conference proceedings where the authors provided camera-ready copy.
Not only is the algorithm fast on the small set, but the results show that it can even be faster for the large set. (This can't be right, run the experiment again?)
2g Writing for Computer Science
When the last line prior to a heading is by itself at the top of a page, or a heading or the first line of the following paragraph are at the bottom of a page, that line is an orphan; rewrite until it goes away.
checking for consistency
Are the titles and headings consistent with the content? Have all terms been defined?
Is the style of definition consistent? For example, were all new terms introduced in italics, or only some?
Has terminology been used consistently?
Are defined objects always described in the same way? For example, if the expression "all regular elements E" has been used, is "regular" implicit in the expression "all elements E"?
Are abbreviations and acronyms stated in full when first used? Are any abbreviations or acronyms introduced more than once? Are the full statements subsequently used unnecessarily?
Are any abbreviations used less than, say, four times?
Do all headings have maximum or minimum capitalization? Has a term been capitalized in one place and not in another?
Is the style and wording of headings and captions consistent?
Is spelling consistent? What about "-ise" versus "-ize", "dispatch" versus "despatch", or "disc" versus "disk"?
Is tense used correctly? Are references discussed in a consistent way?
Have bold and italic been used logically?
Are any words hyphenated in some places but not others?
Have units been used logically? If milliseconds have been used for some measurements and microseconds for others, is there a logical reason for doing so? Is the reason clear to the reader? Has "megabyte" been written as "Mb" in some places and "Mbyte" in others?
4|
1
Editing
127
Are all values of the same type presented with the same
precision;
Are the graphs all the same size? Are the axis units always given? If, say, the i-axes on different graphs measure the same units, do the axes have the same label?
Are all tables in the same format? Does the use of double and single lines follow a logical pattern? Are units given for every value? Are labels and headings named consistently? If, say, columns have been used for properties A to E in one table, have rows been used elsewhere? That is, do all tables have the same orientation?
Has the same style been used for all algorithms and programs? Is there a consistent scheme for naming of variables? Do all pseudocode statements have the same syntax? Is the use of indentation consistent?
In the references, has each field been formatted consistently? Have italics and quotes been used appropriately for titles? Is capitalization consistent? Are journal and conference names abbreviated in the same way? Is the style of author names consistent? Has the same core set of fields been provided for each reference of the same type?
Is formatting consistent? Has the same indentation been used for all displays? Are some displays centred and others indented? Do some sections begin with an unindented paragraph and others not?
Do the parentheses match?