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.
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.
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.
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. 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.
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 polynomial-time approximation algorithms?'' or ``What does the theory of probabilistic proof checking say about such performance limits?''
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.
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.
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.
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.'').
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.
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 ver batim.
In the conclusion, you should explain what it all means to you. If you discuss philosophy, do so in the discussion section.
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.
Be sure to explain your procedures in sufficient detail so that other researchers can verify and replicate your findings.
Print any source code on 8.5 x 11 inch paper with carefully inserted pagebreaks. If your listing comes out of the printer with the pages attached to each other, then burst the listing (i.e. separate the pages and arrange them like pages in a book) before handing in the listing.
In addition, I recommend that you make your report available on the WWW using your favorite hypertext language (e.g. html).
I evaluate source code on the basis of its correctness, completeness, design, modularity, documentation, coding, user interface, and testing.
I strongly recommend that you prepare your written report using a document preparation system. Such systems enable you to edit your document the numerous times required to create excellent prose. In addition, they will enable you to produce high-quality printed output. If you do not already know such a system, now is a good time to learn. I 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. indexing and cross referencing). 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, I recommend the program xmgr, which runs on the SGI workstations.
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.