Write It Right
The Very Basics
by Judy Goldsmith and Robert H. Sloan
This is the first of a series of articles on technical writing. As computer science professors and professionals, we read a lot of other people's technical writing: student assignments and papers; drafts of theses and dissertations; workshop, conference, and journal submissions; grant proposals and white papers; and of course, emails from students and colleagues. We are also the sort of cranks who know that one of the uses of the semicolon is to punctuate a list where at least one member of the list contains an internal comma.
At least one of us has become a compulsive editor, finding typos and poor writing on cereal boxes and billboards as well as technical materials. Both of us wish that everyone else would learn how to write.
To that end, we wrote a rather lengthy article on technical writing. We learned, to our surprise, that not only are there some people who have not learned how to write, but there are quite a few technical journals and magazines that consider the topic of writing well outside of their scope.
Thus, we are offering a series of short articles to assist readers in improving their writing. We hope that, in the course of the articles, we can entertain and inform.
We begin our series with an article about the very basics: understanding your audience, organizing your writing, understanding the importance of grammar and spelling, understanding the revision process, and writing abstracts and summaries.
Audience
When you sit down to write about anything technical, your goal is to communicate with some person or group of people. To do this well, you need to know who your readers will be. What can you assume about their knowledge of the field? Do they know basic definitions and related work? Are they specialists in the area? Do they have theoretical or hands-on knowledge of the area? How broad a range in knowledge can you expect?
Once you know your audience, write for them, not yourself. Define all of your technical terms, unless you are sure they will know them. If you are not sure whether something is a technical term, try it out on the clerk in the supermarket, or some other non-computer scientist. Try it out on a computer scientist or programmer in a different field.
Organization
Your final document should be organized. For most writers, this means planning the organization ahead of time. By all means, start with brainstorming what should go into the paper, if that helps you. However, next you must put a structure on the ideas. Furthermore, you must make that structure evident to the reader by using named sections and giving a "road map" of the document somewhere early on. The most common place for such a road map to appear is at the end of the introduction section.
While that may seem trite, that is where your readers are likely to look for it. Do not disappoint them without a reason. (A typical reason to change would be if one were writing the odd paper where the first two sections are both introductory, as opposed to the more common case where the second section is either related work or formal notation.)
Organization extends to the paragraph and even sentence level. A sentence should contain one idea and one subject. Paragraphs should contain one topic. The first sentence of the paragraph should indicate that topic. Although most paragraphs should have three or more sentences, it is better to err on the side of short paragraphs occasionally.
Grammar and Spelling
Correct grammar and spelling help set an appropriate tone for your writing. Correct use of language indicates professional material, and eliminates many of ambiguities. However, you can not rely on your spellchecker, because of misspellings that are nevertheless correct words. There is a subtle difference, for instance, between the use of "ethics" and "ethic," in writing about, say, safety-critical software development procedures, and a vast difference between "ethics" and "ethnics." A formal tone is appropriate, though overly formal writing can be hard to read. Occasional humor can make a paper easier to read and more memorable, but humor at the expense of any group of people is never appropriate.
Importance of Revision
Just as a car shopper should not fall in love with a particular car until prices have been negotiated, you must not fall in love with your own words: Neither particular examples, nor phrases, nor technical names. Consider the case of the grad student who named her object of study "E.T.," after Exponential Time. Unfortunately, her interview talks happened just after the movie E.T.: The ExtraTerrestrial came out.
Good technical writing is revised and revised and revised again. Once you think a paper is finished, you should read it once for correctness, once for consistency, and then once for grammar and spelling. If you are going to name something E.T., you do not want to refer to it as e.t. or ET or F.T.
Abstracts and Summaries
Almost all technical documents start with an abstract or summary and end with conclusions. Those should be written last, when you know what it is that you have written, rather than what you intend to write.
The abstract or summary should state the problem, very briefly describe the problem if the audience is not expected to be familiar with the problem, and state the solution that the paper offers. Know your readership, know what they can be expected to know about your subject. Write for your readers, not an ideal reader.
In the Next Installment
The next installment will introduce different forms of technical writing and the expectations that go with these forms. For each form of writing, we give the intended audience, the expected content, and the expected review process. In later installments, we will discuss the review process, the issue of coauthorship, the uses of other's research, some of our pet peeves on the mechanics of writing, and ways to present experimental work.
****************
Judy Goldsmith is a computer science professor at the University of Kentucky. Her research interests include decision making under uncertainty; automation of information elicitation; preference elicitation, representation, and aggregation; computational learning theory, and structural complexity.
Robert H. Sloan is a professor (and acting department head) of computer science at the University of Illinois, Chicago. His research interests include application of computer science theory and alorithms to problems from artificial intelligence, especially machine learning ("computational learning theory") and knowledge representation;computer security, especially access control; and computer science education.
.
