Technical Writing

This page, put together by Jim Bednar, summarizes solutions to some problems typically found in student writing, based on experience grading Lisa Kaczmarczyk's Technical Writing course and other CS courses. There are several sections:

Structure, flow, and composition

What is your thesis?
Coherent works like essays, papers, theses, books, etc. should all have have one main topic (the "thesis") that is clearly evident in the introduction and conclusion. Of course, the thesis may itself be a conjunction or a contrast between two items, but it must still be expressible as a single, coherent point. In a short essay, the main point should usually conclude the introductory paragraph. In longer papers or books, it may conclude an introductory section or chapter instead. Regardless, the reader should never be in any doubt about what your thesis is; whenever you think it might not be absolutely obvious, remind the reader again.

Say it, do not just say that you will say it
In the introduction, conclusion, and abstract (if any), do not merely describe what you are going to say or have said, actually say it! For instance, students writing essays about a journal paper often use an empty introduction like "I will discuss and evaluate this paper". Instead, if you will later argue that e.g. the paper was ineffective, you should state that the paper is ineffective, and (in brief) why you believe that to be the case. Then you can elaborate on that point in subsequent paragraphs.

Overall structure
The standard format for an effective essay or article is to: (1) present a coherent thesis in the introduction, (2) try your hardest to convince the reader of your thesis in the body of the paper, and (3) restate the thesis in the conclusion, tying the whole paper together to fully establish that point. Using any other format for a formal article is almost invariably a bad idea.

Each paragraph is one relevant sub-topic
Each paragraph should have one topic that is clearly evident early in the paragraph. Just as important, each paragraph's topic should have a clear relationship to the main topic of the paper. If that relationship is not clear, either the paragraph should be eliminated, or the main topic should be revised.

When in doubt, use the recipe: introduce, expand/justify, conclude
The structure for a paragraph is usually the same as the overall structure -- first make the topic clear, then expand upon it, and finally sum up, tying everything back to the topic. The same advice applies to writing subsections, sections, chapters, books, and so on. At each level, you need to tell the reader what you will be trying to say (in this paragraph, section, etc.), then you need to cover all the relevant material, clearly relating it to your stated point, and finally you need to tie the subtopics together so that they do indeed add up to establish the point that you promised.

Transitions are difficult but very important
Each sentence should follow smoothly from the preceding sentence, each paragraph should follow smoothly from the preceding paragraph, and so on for sections and chapters in larger works. The goal is to make sure that at every step the reader knows where you are going before you get there. Even if your overall context is a poorly-structured jumble of ideas, anything that a reader is expected to read from start to finish needs to be a linear progression along one single path through that jumble.

Transition words and phrases are what makes such a feat possible. Without good transitions, the reader will end up backtracking repeatedly, which will usually cause your point to be lost.

In practice, making smooth transitions is very difficult. Learning to do it takes a lot of practice at first, and actually making the transitions smooth takes a lot of effort every time you write or revise something. One rule of thumb is that every time you switch topics, you should try to provide a verbal clue that you are doing so, using transitions like "However, ...", "As a result, ...", "For comparison, ", etc. Apart from that, all you can do is read and reread what you write, rewording it until each new item follows easily from those before it.

Stay on topic without being one-sided
To avoid being misleading, you will often need to acknowledge some weaknesses in your argument or discuss some merits of an opposing argument. It is quite appropriate to discuss such opposing views when they are relevant, i.e., when they relate directly to the main topic of your paper. For instance, if you argue that a paper was not written well overall, it is usually a good idea to point out the few things that were done well, e.g. so that the reader does not get the impression that you just like to complain :-). Often such opposing observations fit well just after the introduction, providing a background for the rest of your arguments which follow. In general, just try to make your own point as clearly as possible, while at the same time not overstating it and not pretending that no other valid viewpoints exist.

Avoid redundancy
To ensure a certain amount of effort and depth of coverage, most writing assignments in academic courses come with page minimum specifications. However, in the scientific and research communities, brevity will be rewarded much more than verbosity. Scientific papers come with page maximum specifications, and never page minimums.

Thus you should learn to avoid redundancy. When two words will do, there is no need to use twenty. When one sentence will do, there is no need to use ten. Whenever you finish a sentence or paragraph, read over it to see if any words or sentences can be eliminated -- often your point will get much stronger when you do so. Extreme example from a student paper:

"No universal definition of the number of pages in a brief paper exists today. Therefore, in general, the definition of 'brief' could be considered somewhat ambiguous."
(Perhaps "The term 'brief' is poorly defined" would suffice.)

Formal writing

Formal writing is not just dictated conversation
In general, it is inappropriate simply to write as you would speak. In conversation, the listener can ask for clarification or elaboration easily, and thus the speaker can use imprecise language, ramble from topic to topic freely, and so on. Formal writing must instead stand on its own, conveying the author's thesis clearly through words alone. As a result, formal writing requires substantial effort to construct meaningful sentences, paragraphs, and arguments relevant to a well-defined thesis. The best formal writing will be difficult to write but very easy to read; the author's time and effort spent on writing will be repaid with the time and effort saved by the readers.

Avoid contractions
Contractions are appropriate only for conversational use and for informal writing; they have no place in a scientific or other formal text.

Write what you mean, mean what you write
Speakers use many informal, colloquial phrases in casual conversation, usually intending to convey meanings other than what the words literally indicate. For instance, we often speak informally of "going the extra mile", "at the end of the day", "hard facts", things being "crystal clear" or "pretty" convincing, someone "sticking to" a topic, readers being "turned off", something "really" being the case, etc. Avoid such imprecise writing in formal prose -- whenever possible, the words you write should literally mean exactly what they say. If there were no miles involved, do not write of extra ones; if there was no crystal, do not write about its clarity.

Among other benefits, avoiding such informal language will ensure that your meaning is obvious even to those who have not learned the currently popular idioms, such as those for whom English is a second language and those who might read your writing years from now or in another part of the world. Formal writing should be clear to as many people as possible, and its meaning should not depend on the whims of your local dialect of English. It is a permanent and public record of your ideas, and should mean precisely what you have written.

Use complete sentences
Except in extraordinary circumstances, sentences in formal writing must be complete. That is, they must have a verb and they must make appropriate transitions between clauses. Phrases with no verb are not complete sentences, and clauses that are just run together are not complete sentences.

Note especially that most "-ing" words are not verbs -- "The sky being blue" is just a clause, not a sentence. To be a sentence, i.e., something that you can use on its own followed by a period, it would have to be "The sky is blue".

Academic writing

Authors, not writers
The people who perform a scientific study are called "authors", never writers, even though the results are presented in a written paper. Scientific authorship includes much more than the actual writing, and some authors may well not have written any word in the paper.

Use last names
Never refer to the authors of a paper by their first names, unless you know them personally. Even then, using the first name would be appropriate only if for some reason you are discussing a personal anecdote about the person, rather than discussing them as a scientific author. First names are rarely even mentioned in the body of a scientific text; the last names are sufficient.

Author names are keys -- spell them properly
In academic writing, an author's last name is like the key in a database lookup -- if the name is misspelled (e.g. "Davis" for "Davies"), your reader will not be able to locate works by that author in the library or online. Moreover, it is quite impolite to misspell someone's name when you are discussing them; doing so shows that you have not paid much attention to them or their work. So you should make a special effort to spell author names correctly, double- and triple-checking them against the original source, and ensuring that you spell them the same way each time.

Use appropriate pronouns for authors
Use appropriate pronouns when referring to authors. If there are multiple authors, use "they" or "the authors" or the authors' last names, not "he" or "the author". If there is only one author and you are quite certain about the gender, you may use "he" or "she"; otherwise use "the author" or the author's last name.

Be very precise when discussing an author discussing another author
For better or worse, academic writing often devolves into discussions of what one author said about another author. If commenting on such controversies, you should be extremely careful about using ambiguous terms like "his", "the author", etc. Very often your reader will have no idea which of the various authors you are referring to, even though it may be clear to you. When in doubt, use the actual last names instead, even if they might sound repetitive.

"A research"
There is no such thing as "a research" in English. Use "a study" or just "research", never "a research". Similarly, there is no separate plural form of research; "researches" is not a word in English.

Referring to other texts
Use double quotes around the title of an article when you refer to it in an essay. Italics are reserved for books or other works of similar length. Avoid underlining altogether --- underlining is just a way of indicating that handwritten or typewritten text should be typeset in italics, and is thus inappropriate when italics are available (as they are on a word processor).

Be professional and diplomatic
When writing about another's work, always write as if your subject may read your paper. When your work is published, that person may very well come across your work eventually. That person may even be in a position of authority over you, e.g. deciding whether to accept your paper, hire you, grant you tenure, etc. Thus it is crucial to avoid pejorative, insulting, and offensive phrases like "the authors attempt to", "the study was a waste of time", "this work is pointless and totally misguided", etc.

If you do find yourself attacking someone else's work, it is a good idea to put down your paper once you've written it, then go back to it later and read it as if you were the person you are attacking. You will probably notice certain key phrases and terms that would make you angry or defensive, and you can go back and re-word these to make your disagreement more academic and less personal. Remember, the fewer enemies you make, the better.

Specific tips

Strive to avoid ambiguous references
Conversation is replete with ambiguous words like "this", "these", "his", "it", "they", etc. These words have no meaning in themselves, but in conversation the meaning is usually clear from the context. In written text, however, the intended meaning is quite often not evident to the reader, because there are e.g. many possible interpretations of "it".

It is a good idea to read over anything you write, searching for this sort of word. For each instance, first ask yourself "To what, precisely, does this term refer?". For such a reference to make sense, the object, person, or concept must have been explicitly mentioned just prior to your reference. Often you will find that "it" or "they" refers to something vague that was not even discussed explicitly in your paper, in which case you should reword your text entirely.

Even if the item to which you refer is explicitly mentioned in your paper, ask yourself whether there is any chance that the reader might not know to which of several items you might be referring. E.g. for the word "he", were there two or three people being discussed? If so then state the actual name of each; "he" would be ambiguous.

Often an ambiguous "this" or "these" can be disambiguated by adding a noun that specifies precisely the type of object or concept to which you are referring. For instance, "this argument" or "this paper" may be less confusing than simply "this".

Watch out for homonyms
Spell-checkers are wonderful, but they are absolutely useless for detecting misused homonyms, i.e., actual words whose meaning is confused with other actual words. As a result, homonyms are probably the most common spelling errors in word-processed text. Even if you are lazy and let the spell-checker fix all of your other words, make certain that you know the differences between words like:

If you do not know the difference, avoid using the words altogether. But since the spell-checker takes care of all the other words you may misspell, learning to use these correctly is really not much of a burden, and is crucial for convincing your readers that you are competent. There are many web sites and books available that will explain these and other homonyms.

Avoid "comprise"
I have yet to see the word "comprise" used correctly in a student paper. Thus even if you happen to be some highly anomalous individual who understands its actual meaning (hint: it is not a synonym for "compose"), you should still avoid using it. Clearly one cannot assume that a typical reader will understand it.

"But" and "however" are not synonymous
The words "but" and "however" have similar meanings, but they are not interchangeable. If you take a grammatically correct sentence containing "but" and replace it with "however", or vice versa, the result will almost always be incorrect. If you do not know the difference (in particular, how to punctuate the words using commas), you should look it up.

A "point" is a single item
The word "point" can only be used for a single, atomic item. Thus it is not appropriate to discuss a "sub-point", "part of a point", the "first half" of a point, etc. Instead use "topic" or "section", etc.

Capitalization
When in doubt, use lower case. Capitalization is appropriate only for specific items or specific individuals. For example, capitalize school subjects only when you are referring to a specific course at a specific school: math is a general subject, but Math 301 is a particular course. Similarly: Department of Computer Sciences vs. a computer science department, the president vs. President Bush. When in doubt, use lower case.
3/31/2003