CS 3604: General Help in Writing Assignments

Fall 2002, Dr. Rosson

Expectations
The writing exercises in this class are intended to give the student further experience in writing in a technical environment. In most cases, writing in organizations is in response to some requirement set by a manager or group leader and has very specific goals and expectations. Perhaps the most frequent kind of writing need (beyond email) you will encounter as a CS professional is a business letters or memos to coworkers, your boss, or higher up administrators. You will also be called upon to help write proposals. Sometimes you will want to write what is often called a "white paper", a more detailed document that describes an issue or other phenomenon that you wish to make others aware of. You may wish to take a stand on the issue and even urge others to take some kind of action. For example, because of the operating system being used, your organization might be highly susceptible to significant damage due to computer viruses but your coworkers aren't aware of the danger and most wouldn't know how it can happen or what to do about it. By way of writing a white paper on the topic and sending it out or posting it, you can raise awareness of this important issue, inform your coworkers by spelling out the technical details, and motivate people to do what it takes to achieve your goal.

We are not trying to get you to write for publication, but even in writing for publication, such as in the Communications of the ACM or IEEE Computer, prospective authors are given guidelines that they are expected to follow. In such cases, it is also useful to get a copy of the questions that are asked of reviewers of potential publications to make sure that the manuscript provides answers to the questions that they are being asked in the process of deciding whether this paper is worthy of publication.

One of the major guidelines to be followed is that the what you write should answer the questions posed by the prospective audience (e.g., your coworkers, your boss, larger groups of people in your organization). The reader (and grader, in our case) should be able to find those answers easily. Frequent use of subheadings or topical sentences in paragraphs can ease this burden. If the assignment contains a description of the questions to be answered, or the topics to be covered, then use that as the initial outline of the report or paper. Immediately you will have solved two problems: * Developed an outline that conforms to the expectations of the reader, and taken two important steps in problem solving:

  • Understanding the problem, and
  • Dividing the problem into subproblems (the divide and conquer strategy).

    Finally, but very importantly: you may have been taught in earlier classes to weave your thoughts into a flowing narrative and make your writing "interesting". However, the major purpose of technical writing is to provide information clearly, and not to try to impress the reader with your fancy wording and clever constructions. Avoid flowery language and "literary" stylism!


    Guidelines for Your Writing
    Unless otherwise specified, each written assignment must be typed and double-spaced with approximately 250 words per page; multiple page assignments must be stapled in the upper left corner. Written assignments that are significantly shorter (or significantly longer) than the assigned length, or that are not stapled, will be penalized in the grading. You will be asked to state the length (number of words) on the grading form for each written assignment. For this requirement, you should use the word count function of your word processor, not just an estimate.

    You are required to staple a grading form (available as a link from each assignment) as a cover sheet to the front of each of your written assignments. This grading form is a guide as to how the written assignment will be graded, based on the following general factors (as applicable to the specific assignment):

    1. Content. Definitions, if appropriate, must be complete and correct. The content must reflect knowledge of the subject on your part. An important factor is your ability to make your own original synthesis of information taken from other sources. You should also avoid repetition. Present each point the best way you can in one place, then don't come back and repeat the same thought somewhere else. The best way to accomplish this is to have a good outline. Without an effective outline, the temptation is to keep making the same points. I repeat: avoid repetition.
    2. Organization. The order in which you present your ideas is crucial to good communication. Your written assignment should always contain an introduction in which you set the stage, saying what the written assignment will be about. This could be a restatement of the assignment in your own words. The introduction is to be a guide to the overall structure the written assignment will take. Each written assignment should also have a conclusion (more than one sentence) and a list of references (as appropriate) at the end.
    3. Structure. Each section and paragraph, as well as the whole written assignment, should start with a topic/thesis sentence, followed by development of that point (only). Make each point well just once. Repetition is often one of the most difficult things to avoid in writing, but it usually dulls the mind of the reader. Within each sentence there should be just one cohesive thought or idea. The development of each topic sentence must include some ideas, evidence, and/or opinions to support the topic sentence. So, in the case of the written assignment itself, it must support the requirement stated in the assignment. In the case of a paragraph, each sentence must serve to support the first sentence of that paragraph. This support can come from your own ideas, the assigned readings, or other outside sources. When you use sources other than your own ideas, you must cite them (this is itself a big issue in ethics and professionalism) and give the reference at the end of the written assignment, including the relevant page numbers.
    4. Style and tone. Because of our stress on professionalism in this course, we require a formal writing style not a chatty one. Therefore, avoid casual or colloquial terms and hackneyed expressions (e.g., "kids," "clobbered"). You should avoid diatribe, hyperbole, idiomatic expressions, clichés (e.g., "all well and good"), contractions, casual language, or trite expressions. Avoid fluff, shooting the bull, and repetition. Repetition is perhaps the single most common writing error. Say it once, the best way you can; we repeat: Don't repeat! Be parsimonious with your own opinions. Most readers want facts and critical and logical thinking. Style also includes the clarity with which you express your ideas. Readers want crisp, clean communication.

      Good writing is interesting, has few grammatical errors, and flows smoothly so the reader doesn't have to work at it. Bad writing has lots of grammatical errors, rambles without any clear point, strings together many quotes without original writing in between, and shows no stylistic variation (e.g., "In 1993, he …. In 1995, he further …. Then in 1997, he …."). Finally, avoid flowery, "purple" phrasing that sounds like romance novels or travel brochures (sophomoric attempts at "sophisticated" writing).

    5. Mechanics. You will be graded on the details of your writing mechanics, a factor in writing quality. Everyone should have access to a spelling checker, so there is no excuse for misspellings or typographical errors. Correct grammar is required (matching number and tense between subject and verb, correct punctuation, and sentence structure, etc). Avoid run-on sentences and paragraphs. Use accurate and precise words, good phrasing, smooth transitions between paragraphs, and parallel construction. Quotation marks and ellipses (. . .) must be used correctly for text taken from a reference. Do not overuse quotations. If a large percentage of your written assignment is quoted text, it will be regarded as an attempt to "pad" its length. We want to see your own writing.

    The Importance of Proofreading and Iteration
    Proofreading and iteration are essential parts of the writing process, and we will take them seriously in this class. Proofreading is more than just skimming through your written assignment. We want someone to really get in there and mark it up, so you can benefit from the process and improve the writing quality. Try to find people who you know are good writers. Iteration means editing and rewriting the same document over and over again, each time improving. When I write a paper for publication, I always do it in a cycle of writing, reading, marking up, editing, and rewriting. It is typical for me to go through this iterative cycle 20 times over a period of six months for a single paper!

    A Warning About Plagiarism
    We will be especially zealous in prosecuting Honor Court cases involving plagiarism from the Web or Internet. Plagiarism of any work from a current or former student in this course is also considered to be an honor code violation. Through the use of peer evaluations and collaborative development, and the use of the WWW, there is a strong possibility that you will be exposed to concepts and ideas that you can use in your own work. Getting permission to use those ideas and concepts from the originator (except when it is already in the public domain) and/or giving appropriate acknowledgment in your own work circumvents a charge of plagiarism.

    All assignments submitted shall be considered graded work unless otherwise noted. All aspects of your coursework are covered by the honor system. Any suspected violations of the honor code will be promptly reported to the honor system. Honesty in your academic work will develop into professional integrity. The faculty and students of Virginia Tech will not tolerate any form of academic dishonesty.

    Grading
    Some of your grade will be determined by the grammar and spelling elements of a written assignment. These are important parts of the core of writing. You usually don't get any credit from the reader for good grammar and spelling; it is simply expected. On the other hand, poor grammar, spelling, and vocabulary can create an impression of ignorance, which can negate good ideas you might have expressed in the content. If the grammar and/or spelling are bad enough to hinder reading of your assignments, we will NOT be able to read and grade such assignments. Use the spelling and grammar checkers on the text but do not rely on the results. There are three additional steps that you can take:

    1. Carefully proof read your work, and if possible have someone else read it for you. Alternatively, read your report out loud as if giving a lecture; verbalization in this manner will help you recognize your errors. In one assignment, there will be a required peer review (graded), which you will respond to in a revision process. In other cases, you will be write a first and final draft, with revisions based on feedback from the GTA and instructor.
    2. Since all assignment statements will be delivered to you well in advance of the due date, write your report, put it aside for a few days and then read it again; you will be surprised how different it will look a second time around!
    3. The University Writing Center is available for your use; they can provide you with both assistance in preparing a draft document, and can give you pointers to improve your presentation. When going to the Writing Center, make sure that you impress on them that these are "technical reports" and that we have guidelines for presentation which you are expected to follow. See the lecture notes to the class on "Writing Plans and Skills" for these guidelines. If you need assistance on grammar, the university writing center provides a "hotline" to which you can submit questions by e-mail. The e-mail address is grammar.hotline@ebbs.english.vt.edu.

    Other Helpful Aids to Writing and Reviewing/Evaluation
    For those of you who are interested in the writing process, or who need additional assistance, Dr. JAN Lee has summarized a well-developed framework for how to approach the entire process of writing (adapted from Joliffe, 1994, p. 6-19). He has also assembled several other resources: