Writing Up a Project

Alan T. Sherman
DRAFT: April 27, 1996

Revised by CB to aim at UR UG Audience, April 2003

Whether you're going into academics, big business, non-profit organizations, self-employment, church volunteer work, or straight to welfare, writing is important. Proposals, business plans, letters, reports, patent disclosures, articles, minutes... if you write better, you're going to DO better.

Your class projects represent a lot of work on your part. Your report should do your hard work credit and thus make sure you get credit for the hard work. The assignments are usually open-ended, in the sense of inviting or requiring a choice of things to accomplish and style of accomplishing them. They usually have scope for experiment, compare-and-contrast studies, and often allow repetitive, organized experimental exploration of hypotheses. The results of these experiments are largely what you are reporting. Check out Scientific American sometime. In those articles, you can just read the figures and the captions and that's all you need to know. Graphics are king. Now in our classes we wouldn't go that far but remember that graphics can be centrally important in getting across your point, and lack of them can cause your point not to get made.

Your class projects are actually technical reports, of the sort that we publish here in the CS Department to document our work. There is a roomful of them on different subjects, and you're invited to check out /u/ftp/pub/papers for a list of them and for several down-loadable ones.

In our assignments, your documented code and README should be submitted separately and not mixed up with the project report.

The Technical Report (TR) is a common written form through which computer scientist communicate their findings. Each TR should have a focused topic that is developed logically along some clearly identified perspective. The major components of a TR are title, author information, date, keywords, informative abstract, body, acknowledgments, references, and appendices. Typically, the body is organized into four sections: motivation, methods, results, and discussion. This document offers advice and specifications for writing TRs.


Overview

Communicating results is a crucial aspect of doing research. Through such communication other people can learn about and benefit from the findings. Often such communication includes a written document known as a Technical Report (TR). The successful researcher must master this important written form.

A TR should explain what you did, why you did it, what you discovered, and what is significant of your findings. The report should identify clearly what is novel about your work, and how it relates to prior knowledge. There should be a focused topic, and an attitude about this topic. The topic should be developed according to the attitude in a thorough, logical, and orderly fashion. Throughout, the author should be helpful to the reader.

The report should include the following components: descriptive title, author name and affiliation, date, informative abstract, list of keywords, body, acknowledgments, and list of references. Additional separate appendices, where appropriate, may also be included. The standard four-part outline for the body of a technical report is motivation, methods, results, and discussion.

For multi-author class projects, (not usually for multi-author TRs or scientific papers) it is important to identify who did what and it's best if each team member writes up his own work. Then the whole thing should be edited for smoothness and consistency (of notation, nomenclature, and style) by the lead author. So there should be a section or paragraph explaining what each team member did.

Also on multi-author projects, it is of course nice if the editor has compatible information to weave together into the final report. I have had terrible luck trying to use other people's WORD documents: LaTeX is much more transparent to incorporate into larger docs. In any event, the editor should make sure he can actually and easily manipulate the chunks his co-authors give him.

There is no minimum or maximum length requirement--the length should be appropriate for what you have to say. Many TRs are about 10--20 pages long, but it is not uncommon for TRs to be significantly longer. Regardless of length, it is usually an effective strategy to explain in successive ``layers.'' For example, lengthy TRs often begin with a relatively short overview section for readers who wish an executive summary. Quality and conciseness, not quantity, will be rewarded. For CS class project reports, 10 pages is certainly not excessive. In fact, spending two weeks to build a program and then not getting 10 pages worth of juice out of it represents an inefficient use of resources on your part.

This document aims to help students learn the basics of computer science technical reports. Although my advice is highly subjective, I hope the reader will benefit from issues raised, even if she disagrees with my particular point of view. [I left this gratuitious political statement in just to keep you awake and to show you that even people who write about how to write still do egregiously annoying things -- CB]. Sorry, I should have said "despite disagreement with my particular POV." Although technical writing is a crucial part of writing TRs, this document is not a tutorial in effective technical writing. Several sources of information about technical writing are listed in the references. The rest of this document describes the following important aspects of TRs: thesis, components, organization, delivery formats, special advice for experimental projects, common mistakes to avoid, additional advice, and other important communication forms.


The (Hypo)Thesis

Every TR should have a thesis or hypothesis -- a topic together with an attitude about the topic. The attitude helps focus the subject and provide a framework along which the topic subject can be explored. For example, the topic might be a neural net excercise and the attitude might be that back-propagation is not the best way to learn weights. The introduction of each TR should clearly identify its thesis and an organizational plan for developing the thesis.

Many researchers find it useful to think in terms of questions and answers. I recommend that you carry out and communicate your research by raising and answering focused questions. For example, you might ask ``What are the performance limits of decision trees?" or ``What does the theory of one-way algorithms have to do with actual cryptographic practice?"


The Components

A technical report should include each of the following items:

  1. A logical, accurate, descriptive, and grammatically correct title. Please note: the title ``My CSC 242 Course Project'' is not descriptive.

    Titles should be as short as possible, while still satisfying the foregoing criteria. Avoid cute titles that violate these criteria. I often like two-part titles because they provide short and long forms (e.g. ``Statistical Techniques for Cryptanalysis: An Experimental Study using Real and Simulated English''). I try to avoid titles that exceed 17 words. [CB wonders: what happened to him when he was 17?]. Also CB notes that lots of people HATE the two part colonized title, so feel free not to use it or to swing either way depending on local politics.

  2. Author name and affiliation, and date. For example, your affiliation might be ``Department of Computer Science University of Rochester.'' You might also like to include the city and state of your affiliation, your email address, and a URL to your home page.

  3. An informative abstract of approximately 200 words. Make sure that your abstract is informative---your abstract should serve as a substitute for your paper. Briefly summarize your main findings. Concretely summarize; do not introduce. Immediately get to the point in the first sentence. Do not cite any references in the abstract, and do not begin the abstract with the weak, hackneyed, and boring phrase ``This paper ...''. The abstract should be informative yet understandable to most researchers in your general field. I like the abstract to fit on one title page, including the title, author name and affiliation, date, and list of keywords.

  4. A list of appropriate keywords. These keywords should identify the field of your report and its major topics. Choose keywords to be helpful to researchers in locating your work in document-retrieval systems. What words and phrases should someone use to find your report? Be specific, and use only standard phrases. Browse some computer science journal (e.g. Int. J. Comp. Vision, AI Journal) to get a feel for what is an appropriate keyword and what is not. Computing Reviews publishes an annual classification system including keywords which many journals follow.

    Many journals use three levels of keywords: general terms (e.g. cryptology), subject descriptors (e.g. differential cryptanalysis) recognizable to most researchers, and implicit terms--specific words or phrases that act as proper names (e.g. RSA Cryptosystem) which might not be recognizable to all readers.

  5. Body of technical report. Write a clear, informative, and thoughtful description and critique of what you did. Where appropriate, include carefully drawn graphs and diagrams. Be sure to motivate, present, and interpret your findings.

    Focus on the scientific content of the project--your questions and answers. Identify and explain interesting and important phenomena. Emphasize what is new about your project. In addition, briefly comment on the engineering aspects of your work: what problems did you face, what decisions did you make, and what are the consequences of these decisions? Although it is crucial to explain your experimental procedures, be concise and do not bore your reader with lengthy descriptions of routine implementation concerns.

    Pay attention to important transitional sentences, especially the first and last sentences of the report. There are three standard ways to begin the introduction: startling statement, dramatic incident, and quotation. I like to end each report with a powerful sentence that concisely summarizes the significance of the entire project.

  6. Acknowledgments. Acknowledge any help you received, including any use of computer equipment. Be specific.

  7. Complete and accurate list of references cited in the technical report. There are five reasons for citing works: to give credit where credit is due, to be helpful to the reader to identify useful related work, and to identify the context and background of your work. Fourth, references give you authority and credibility that you know what you're talking about, and don't allow people who have done similar things to feel slighted and ignored if they're mentioned. Last, a backwards reason: references are the symptom of what should be going on anyway, namely that you find out about the field you're writing about. In this case the symptom helps cause the effect, namely that you might actually read the literature and find out the state of the art of your subject. Adopt a bibliographic style used by some major refereed computer science journal (e.g. use the style for the \it Journal of the ACM\/). CB: if you use LaTeX, you have a choice of dozens of bibliographic styles that use a database of references in standard form. This database never changes format, grows through time, and can be used in all your writing, the appearances changing as necessary. Neat, eh? When last I looked, Word was clueless about options, but Endnote worked. So in the case of Word, you just copy the format every time.

    I like to list and number references by alphabetical order of author name. When citing references in the body of the report, always explain why the reference is being cited. For example, do not cite previous work without critically explaining how it relates to your work. I like to mention the author name in the textual citation, followed by the corresponding reference number (e.g. ``In 1976, Diffie and Helman [14] proposed the concept of public-key cryptography.'').

  8. Appendices for supplemental information and for information that is too detailed or voluminous to fit into body the of the technical report. On the other hand, dumping reams of raw output or input data, or pages of low-impact computer code (like GUI programming) is rarely ever done. Distill, understand, analyze, present graphically!

Organization

Although you are free to organize your report in any way you see fit, I highly recommend that you organize the body of your report along the following standard outline for scientific papers:

In thinking about organization, I find it helpful to separate logical organization from explicit numbered sectioning. For logical organization, I think in terms of hierarchies. Part of the organizational task is to embed the logical organization into numbered sections. For example, the logical introduction might include one or more numbered sections, depending on what needs to be said. A short report might begin with one section: 1. Introduction. A longer report might begin with a more elaborate logical introduction consisting of four numbered sections: 1. Introduction 2. Overview 3. Background 4. Previous work. As the report evolves you may wish to modify the organization.

CB: Personally I don't like "Introduction" as a title since it's too boring and predictable and general. I like "Background and Motivation".

In describing the purpose of your project, restrict yourself to scientific and engineering reasons; do not discuss reasons that are related only to school. Do not repeat sentences from the abstract verbatim.

In the conclusion, you should explain what it all means to you. If you discuss philosophy, do so in the discussion section. Remember that the abstract and conclusion are often all that gets read in a paper so make sure the whole story, with points you want to make, is here.


Special Notes on Experimental Work

Be sure to explain your procedures, to present your results, and to interpret your results. Summarize your findings in meaningful ways, visualizing important data (e.g. in graphs) whenever possible. CB: YES!

If you are experimentally measuring the running time of a computer program, test your program on many randomly chosen inputs of a variety of sizes, including large inputs. Since the behavior of your program might vary significantly among inputs of the same size, for each input size, try several inputs of that size and report the sample mean and standard deviation for that size; do not simply try one input per size. CB: simple, obvious, important.

Be sure to explain your procedures in sufficient detail so that other researchers can verify and replicate your findings.


Delivery Forms

CB: For us, PDF in the dropbox is it.

Evaluation

We evaluate each report on the basis of its scientific merit, effective presentation, and appropriateness for assignment. We reward thorough analysis, originality, and insightfulness. Scientific merit includes correctness, significance, novelty, nontriviality, and completeness.

We evaluate source code on the basis of its correctness, completeness, design, modularity, documentation, coding, user interface, and testing.


Basics to Remember

Adhere carefully to the following guidelines:

  1. In the introduction of your report, clearly identify a focused well-defined question. Answer this question in the rest of your report.

  2. For multi-author class projects, it is important to identify who did what and it's best if each team member writes up his own work. Then the whole thing should be edited for smoothness and consistency (of notation, nomenclature, and style) by the lead author.

  3. Analyze and interpret your data, and discuss the significance and limitations of your findings. Do not simply report your data.

  4. Be sure that your technical report is complete in the sense that it has each of the following components: descriptive title, author name and affiliation, date, informative abstract, list of keywords, body, acknowledgments, and references.

  5. In your abstract, specifically and concretely state your findings; do not vaguely describe what you set out to do. Your abstract should summarize, not introduce. Do not begin your abstract with the hackneyed phrase ``This paper.''

  6. Don't forget other local resources like Writing Infelicities to Avoid. and this Technical paper checklist.

Additional Advice

Start early and do not wait until the last moment. Expect system downtime and personal illness, especially the week before the project is due.

We recommend the Latex system because it and its relative TEX produce high-quality results for mathematical typesetting, and Latex provides high-level document support (e.g. reference and citation management, indexing and cross referencing). Better yet, it's much easier for an editor to modify a paper or edit together several papers in LaTeX. I've found Word absolutely horrible for changing other's docs or incorporating them into a unified larger text. As for text editors, I recommend Gnu Emacs because it is powerful, extensible, customizable, and self-documenting.

For drawing graphs and doing statistical analysis of your data. There are many packages, including Matlab, Excel, and gnuplot.

Whenever working on a large project, you should save your notes and preliminary drafts. Many people find this material useful, and it will be helpful to you if you are ever challenged to show that the work is your own. In addition, you should keep a copy of the final report in case the original is lost. CB: Never give a prof an original!


Other Important Communication Forms

Other written forms of technical communication important to researchers are: grant proposal, white paper, extended abstract, journal article, research monograph, conference proceedings, cover letter, letter of recommendation, and job application letter. Important oral communication forms include: conference presentation, technical lecture, dog-and-pony show, telephone conversation, and job interview. These topics are beyond the scope of this document, but good writing is good writing. Get a copy of Strunk and White and put it under your pillow. It's very small and very concentrated and very good.

References

  1. Miller, Casey, and Kate Swift, The Handbook of Nonsexist Writing, Harper and Row.
  2. Sherman, Alan T., ``How to solve and write up homework problems'' (January 29, 1991).
  3. Higham, Nicholas J., Handbook of Writing for the Mathematical Sciences, SIAM Press (1993).
  4. Dornan, Edward A.; and CHarles W. Dawe, The Brief English Handbook, Little, Brown and Company (1984).
  5. Letitia Baldrige's New Complete Guide to Executive Manners, Rawson Associates (NY, 1993).
  6. Strunk, William Jr.; and E. B. White, The Elements of Style, Macmillan (New York, 1972).

Alan T. Sherman, sherman@cs.umbc.edu
Last modified: April 27, 1995