As course assignments, technical reports serve a few purposes. Often, they provide a way to communicate some work you have done to the course instructor, whether completing a lab, performing an analysis, developing some software, etc. This allows for assessment and for helpful feedback if needed. Always, though, they are practice for technical writing skills that will be important in any work you do after graduation. Saying, “Yeah, I did it; here it is,” is rarely sufficient; your manager, client, advisor, coworkers, or colleagues need context, background, process, pitfalls, results, and all the rest to really know what you did and accept it. The organization, flow, writing mechanics, and clarity are also important aspects of this communication.
All of the following is important, so please do pay attention and let me know if anything is unclear. I do not want to have to copy any of the below points verbatim into report feedback…
The following applies to technical reports in general. Certain classes have additional specific guidelines:
- CS256 - Computer Organization and Architecture - Lab reports
- CS354 - Algorithm Design and Analysis - Empirical analysis reports
Audience¶
Writing is communication, and communication is only effective when it conveys the intended information or has the intended effect on the audience of that communication. Keeping the audience in mind is critical, then, for writing effectively. Different audiences need different things for writing to be effective.
In “real” technical writing, you will usually have an audience in mind and know something about their background and what the goal of the report is for them, and that should guide the choices you make in your writing.
In writing for a class, you often must assume a particular audience and practice writing for that imagined group of people. For most class reports, unless specified otherwise, assume the audience of your report is students like you, with a background similar to what you had before you began the work you’re writing about. The goal of your report should be to explain your work and your results in sufficient detail for someone with that background to A) understand, and B) be able to reproduce your work.
Report Format¶
Reports should be a professional document describing your work in enough detail that it could be replicated by another with your background, including all designs, experiments, and data gathered. Technical reports generally use something like the following organization:
-
Title:
Title, course, your name, any partners’ names (if relevant), date(s) worked (if relevant), and date submitted. -
Introduction:
Describe the goal(s) of the work, and include any relevant context or background information (e.g., from the lectures or the reading) that the intended audience might need to understand what follows. It is often useful to provide a brief summary of your results and outcomes here as well. -
Experiment/Methodology:
Describe what you did. The details here will depend on the type of work you are doing. Specific suggestions for reports in particular classes are linked above. -
Results/Analysis/Discussion: Discuss the outcomes of your work. If you gathered data, present and analyze it here. If you were trying to answer some question(s) or test some hypothesis, provide the answers and/or results here, supported by any data gathered during your work. If an assignment posed explicit questions for you to answer, this is often a good place to do so (though some answers may fit more naturally elsewhere).
-
Summary:
Summarize the process and outcomes of the work as they relate to the objectives. What did you learn? What conclusions can you draw from what you did and observed? What further work or exploration could this lead to?
Not all reports have to follow this outline exactly, of course, but it provides a good starting point. Often with labs that have multiple independent parts, for example, it may make more sense to break the report into parts, where each part contains its own methodology and results/analysis. This works well if there are many different steps for which it makes more sense to keep the separate results close to the methodology that produced them.
Keep the audience in mind while writing, and consider it from their perspective: what organization will be most understandable and flow well?
Guidelines¶
Many of the following are quoted or adapted from these guidelines for writing lab reports in a class at the University of Pennsylvania.
Writing¶
-
Keep your reader in mind always. The reader should understand your report (purpose of the work, process and results, and conclusions) in one reading without having to go back and forth within your paper, and without access to the instructions or questions you were given.
-
Keep your report as succinct as possible without leaving out necessary detail. Every word should count.
-
Technical writing needs to be very careful with technical terms and concepts. Words often have very precise meanings, and it is important to use them correctly. Further, the audience will often not be familiar with all of the terms you use, in which case those terms should be defined clearly when first used.
-
Try to step back from the list of questions you were given for an assignment, if any. Simply answering a list of questions does not prepare you for professional technical writing. The answers should be in your report, but an organized and coherent report will not read like a list of answers.
-
Talk about other interesting things you stumbled across in the course of your work which were not included in your aims. However, use careful wording and organization to make sure that the reader can keep sight of the main point of your conclusion, which is to relate your results to your initial aims.
-
The writing should usually be a narrative. Don’t just provide bullet points of technical details, answers to questions, and raw data. Describe and explain what you did to give context to the details, answers, and data.
Organization¶
-
With any writing, organization is important for maintaining a logical flow of ideas throughout. In technical writing, this can be even more important, as the writing may be read as a single, complete piece or by referencing one or more specific sections from the whole.
-
Use explicit section headings to clearly denote major sections of the writing. Format them to stand out visually from the rest of the text (larger and bold is usually a good choice).
-
Write a clear introduction and conclusion to provide context up front and to summarize at the end.
-
Think about how to organize your points to group them and avoid tedious repetition of equivalent or similar details.
Formatting & Presentation¶
-
Consider numbering the sections of the report. Doing so will make it easier for you to refer to another section or subsection if you need to.
-
Label and caption figures and tables. Figures, for example, should be called “Figure 1”, “Figure 2”, etc. (or include the section number, such as “Figure 1.3” for the third figure in section 1) with a brief descriptive caption for each. Then, you can easily refer to them in the text. Referring to figures and tables by name avoids any ambiguity that something like “the figure above” can introduce.
-
Make sure information in a given section or subsection of the report belongs there. Avoid restating information or reproducing the same graphic in later sections or subsections; instead, refer the reader back to the relevant part of the report (“As stated in Section 2.3, …” or, “These figures are given in Section 2.3.”).
-
Avoid cutting up sections at the end of a page, or stranding a graphic or equation on a page separate from the explanation. If only one line of a new section will fit at the end a page, move the whole section to the next page.
-
Definitely never split a table across two pages. If it is such a large table it doesn’t fit on one page, think carefully about whether it needs to be that large and contain that much information.
-
Many word processors default to spanning a table across the full page width, but most tables don’t need to be this large. They’re easier to read when more compact.
-
To draw diagrams of any sort with the highest quality and the most control, use a vector graphics editor
(such as Inkscape, which is free, open-source, cross-platform and excellent, or Diagrams.net, which is simpler and can be used for free in your browser) as opposed to a raster editor (like MS Paint or Adobe Photoshop). Vector graphics will let you copy, move, and generally edit your drawing with far more flexibility than a raster graphics program can. And including vector graphics in your document will allow them to be viewed on screen and printed on paper at the highest possible resolution. -
Generally, figures should be centered on the page with a caption centered below them. Italicizing the caption helps it stand out visually from the rest of the text. Consider the size of each figure: they should not be so small that details are difficult to discern, nor should they be larger than needed to clearly see all details, as that wastes space on the page.
-
When including code or terminal output (shell transcript) in a document, format it with a monospaced font
. Consolas, DejaVu Sans Mono, and Menlo are all good choices that are commonly available. -
Any block of code or terminal output (anything not included inline as part of a sentence) should be indented to stand out from the regular text. It may be placed in a numbered, captioned figure if it is important and/or if it is referred to somewhere other than immediately before or after the code.
-
Do not include code or a shell transcript as a screenshot of the code from a webpage, text editor, or terminal. Doing this produces a raster image of the text that will be low-resolution, pixelated, impossible to highlight and copy, and inaccessible to anyone using screen-reading software.
-
Blocks of code should be colored with syntax highlighting to improve readability. Avoid the temptation to just take a screenshot of the code from your syntax-highlighting editor, though. Some IDEs will produce code with syntax highlighting when you copy from them and paste into a word processor. There are also web-based syntax highlighters whose output can be copied and pasted into your word processor. ToHTML is one option; you might find another you like more. Shell transcripts do not need to be highlighted; there is no single language or syntax in use in a command line shell, so automatic coloring is difficult or impossible.