Writing Research Papers

We will discuss good technical writing in depth in the third part of the course. For now, here are the principles. Note that just as we speak about "Programming in the Large" and "Programming in the Small", the same concepts can be applied to technical writing.

  1. Stream-of-consciousness on the first draft: Write fast, and capture as much "raw material" as possible. No excuses about "writer's block". Write first the part that inspires you, and don't worry about chronological order.
  2. Technical Writing in the Large
  3. Technical Writing in the Small

Stream-of-consciousness: First draft

Just write in "stream-of-consciousness". The rule here is never to go back and delete. If you are tempted to delete or modify, just insert a note there about how you want to revise this. But mostly, you should be writing only near the end of your text (appending to the end). If you have several concepts to describe, then split your text into sections (blank line, "===" markers, or whatever), and then use this stream-of-consciousness within each individual section. Feel free to skip around, and append to different sections as the inspiration strikes you.

Technical Writing in the Large

Split your first draft into paragraphs. A topic sentence should provide an overview of what is discussed in a paragraph. Once you have your paragraphs, see if it "tells a story". Optionally, you may use the topic-sentences.py Python script to extract your topic sentences into a separate file. This may help to give you the "distance" from your writing and provide an external perspective.

In particular, in the "old days", you were told to first develop an outline, and then fill it in with text. But this Python script will now automatically give you an outline for the paper. So, you can just think about what you want to say, and then every so often, you can use the Python script to "output" your outline. Then look at the outline, and if it's not quite the story you wanted to tell, then the outline shows you where to go back and fix your writing.

After reading your topic sentences, see if the "story" makes sense. If it doesn't, then you may need to use one of several strategies:

  1. If your story skipped something important, then maybe you buried some important information in the middle of a paragraph. If so, consider splitting that paragraph into two, which allows you to insert a new topic sentence.
  2. Maybe, if the story skipped something important, then you might have missed writing something important for the reader. Go back and insert a new paragraph explaining the missing information.
  3. If your story has some "extra" sentences that make it hard to read your story, then maybe you have split too many paragraphs. Consider joining some paragraphs together, to eliminate the distracting topic sentence.
  4. Finally, revise your topic sentences according to the principles, below, in "Technical Writing in the Small". Does the "stress" of the preceding topic sentence match the "topic" of the current topic sentence?
  5. And re-read, again, your story in topic sentences. Notice that you are now playing the role of a reader, as discussed in Reading Research Papers.

Technical Writing in the Small

Each sentence has a natural topic (usually, but not always, the subject of the sentence. Each sentence also has a natural stress (usually, but not always, the direct object of the sentence). The rules of writing in the small are:
  1. The stress of the last sentence should "match" the topic of the next sentence.
  2. How does the stress match the new topic? If it's not completely obvious, then use an optional connector phrase to explain how the stress matches the new topic. Some examples are:
    "In general", "For example", However", "A counter-example is ..., which ...", "This is analogous to ..., which ...", "This is related to ..., which ...", etc.
  3. As always, rules are made to be broken. In some rare cases, you may want to instead use the pattern of "Parallel Constructs": If you use parallel constructs, try to keep the same grammatical structure in each of your sentence, so that the reader can easily parse your "template grammar".
If there is one principle to unify these rules, it is to always steer toward the reader's expectations of what comes next. If you use these stylized rules, then the reader quickly slots each new idea into its proper place. Don't make the reader go back and re-read a previous sentence, because they're not sure how your ideas are connected.

And some smaller bits of advice on writing:

  1. Here is a rich selection of connecting phrases, often used in technical articles:
    therefore, so long as, because of, yet, due to, more generally, however, specifically, especially, in the case of, next, then, while, in order to, 'below' or 'above' (citing earlier or later text), because, since, for details ... see ..., as shown in, as seen in
  2. Mostly, try to avoid pronouns. It's okay to keep repeating the actual phrase that the pronoun refers to. Don't make the reader search backward and guess the phrase being referred to.
  3. Avoid synonyms where possible. It may seem redundant to constantly use the same phrase for the same concept, but it makes the reader work harder when you switch to a new phrase for exactly the same concept.