Notes from "Writing and Revising Technical and Scientific Documents"

A Seminar in the Doctoral Programme, University of Jyvaskyla, Summer 1999

Lecturer: Sharon H. Nelson, Metonymy Productions

Documented by Vladislav V. Fomin

August 1999, Revised December 1999

Purposes And Protocols

• What is the primary purpose of the work? Evaluate honestly whether your primary purpose is to achieve publication or to make a significant contribution to the scientific community.
• Who is your audience? Try to identify potential readers and write for them.
• Write as if your reader is highly intelligent and totally ignorant!
• Make your reader feel good. Make the reader feel smart rather than that you are smart. It is more productive if the reader remembers the content and argument of a piece than that the writer is clever.
• Do not claim that your work is comprehensive; let others praise it. Avoid using the word "great" when describing qualities of your paper or ideas. The fewer claims you make, the easier it is for a reader to see the material.
• Give as much credit as possible to everybody who has contributed in any way to the project or the paper.
• In writing, organizing, and formatting, treat the reader with courtesy.

Organizing Material

Content

• It is very important to state the question you are answering or the problem you are solving. The work is in refining the question. When the question is refined sufficiently, the answer will come easily.
• The question defines the content. The content defines the design. Once the content has been defined, the material can be organized and formatted.
• Write the key issues at the beginning of the paper, not at the end.
• In the introduction do not introduce the field but what are you doing.
• Important! Do not bury the result of good research work in the middle of the paper. Make it visible to the reader.
• If you do not describe your methods, there is no "application".
• If something is important, demonstrate it!
• It is counter productive to write an abstract or a title before the paper is completed and edited. We discover as we write. Do not put yourself into a box by writing an abstract and then refusing to deviate from it.
• Do not try to fit the content of original research into a predesigned format or formula. A formula is designed to contain what has been done previously.
• Some people work most productively by writing at length rather than by following an outline. If you produce a lot of text, see what's important, then refine, and shorten.

Format

• The table of contents is not intended to provide the reader with numbering but to provide an outline of the structure of the article. Make the outline mean something -- it must make sense.
• Another way to provide clues and keys for the reader is to list figures, tables, etc., and to put them in the Appendix as follows:

  Appendix

    1. Figures

    2. Tables

    3. Further reading

• Sections in a paper must be sequential; each following section is a continuation of the previous one.
• See if each section heading relates to the material actually in that section.
• Look at whether section headings extend from or develop the idea expressed in the title of the paper.

Writing

Sentences

• Look at the sentence as a diving board -- it should lead you to the next sentence.
• Do not use a passive voice if you want to continue the discussion.
• Avoid using pronouns, for example, "It" or "This", at the beginning of a sentence, especially if the antecedent is not self-evident. "It" may not be obvious.

Diction

• The word "have" is a weak word. Use, for example, "comprises" instead of "have" where appropriate.
• In systems analysis use the word "deconstruct" rather than "decompose". Corpses decompose.
• If using "we" when there is only one author, refer to colleagues at least in the introduction.
• When using a word in the plural - for instance, "benefits" - make sure you can name two and defend every instance. Do not use words such as "many", large", "broad", "huge" unless you can define how many, how large, etc. For example, "many benefits" has no content unless at least some of the benefits are stated.
• "Critical" is an emergency situation word. Unless you are talking about life and death, avoid using this word. There are other words, for instance, "important".

Punctuation

• Punctuation can change the meaning of a sentence. The following two sentences have different meanings, depending on how they are punctuated. A woman, without her man, is nothing. A woman: without her, man is nothing.
• When using lists that start with bullets or dashes, do not use semicolons at the ends of lines. Put a period after a full sentence. Bullets and dashes separate blocks of material. The semi-colon connects parts of a sentence or list.

Common Errors

• Do not propose in the conclusion. A proposal is not a conclusion.
• Avoid using the words "main contribution" in the abstract. An abstract should state explicitly the main contribution of the work.
• Don't say that something is obvious. If it is obvious, why write about it? If something is not obvious but you state that it is, the statement may confuse the reader. Occasionally, it's convenient to use "obviously" in an argument or explanation. Suppose there are two ways of doing something, only one of which is obvious: "A obviously, but also B."

Argument

• Generalizations must be grounded and supported by particulars.
• Make all arguments explicit. State what you know. Make sure nothing is left out of an argument.
• Beware of connectors that don't connect. "Thus" and "therefore" may appear where there are no connections or the connections have not yet been made. "Thus" is not a magic word! Do not use it where there is space for a truck to drive.

Style and Formatting

General

• The purpose of formatting is to increase readability and to make structures and connections explicit.
• The journal to which a paper has been submitted has the final decision about the style and formatting of a text. If the author refuses to adopt that style and format, the article may not be published.

Quotations

• Quotations should not be longer than 3 lines.
• When quoting, try to use only one line and then summarize.
• Show the relevance of the quotation to your paper. Lengthy quotations fill up space.
• When using quoted material, it is absolutely necessary to have a frame for it: the introduction and the explanation. What is illustrated? What is argued?
• When quoting someone else's material, make absolutely sure that you format it as a quotation, even if you are quoting "only 4 words".
• Should the quotation be too long, break it up into several parts and comment on each of the parts.
• Quote material only if it's essential to do so.

Acronyms and Abbreviations

• Be aware of the introduction of terms that require definitions. Spell out the definitions for the reader!
• When introducing an abbreviation, first provide the full name and then give the abbreviation.
• The reader must be able to concentrate on your ideas rather than on trying to remember acronyms.
• When giving an acronym in a language different from that of the paper, choose a style that communicates the most information in the most logical order using the least space, for example: VTT [Valtion Tekninen Tutkimuskeskus (Centre for Technical Research of Finland)].

Figures, Tables, Appendixes, References

• When using "see" within a text, do not put it in parentheses: See Fomin, p.2.
• When referring to an URL, provide the date in a full format (DD.MM.YYYY) so that the reader can check whether the material obtained at the URL is the same as that cited. New or up-dated versions at an URL may make citations obsolete and exact references difficult to find.
• The Reference List and Further Reading are two separate lists. The FR can be enormously helpful for the reader.
• When drawing and placing figures, consider the convenience of the reader. Try to place discussion adjacent to figures. A reader can't be in two places at once.

Reviewing, Editing, Revising

• Editing is a bottom-up process.
• When you are editing a paper, look at what the paper says rather than what the abstract claims it says.
• When revising a paper, look first at the content rather than the writing style.
• When reviewing a paper or suggesting ways to revise a paper, concentrate on the paper itself, not on what the author has done. (Does it make any sense?) Avoid personal comments to the author.
• To make sure that a paper makes sense and is ordered logically, disable all the formatting features, take away all the headings, remove the section numbers, and read what is written.
• Use different coloured markers to trace related ideas or to flag particular kinds of problems through the text.
• Print as often as needed to see the whole document and to make sure there are no computer-assisted or computer-generated errors or repetitions. Double-space the text so that there is plenty of room on each page to make notes and revisions. Do not double space the tables.
• When in doubt, leave it out.

Sharon H. Nelson. 23 May 2000.