Guide to Writing Reports for Capstone

Due to their large scope and duration, Capstone projects have specialized documentation requirements. This web page provides guidance on how to document your Capstone project.

General Advice

The primary objective of an engineering report is to transmit technical information to individuals having training comparable to that of the author. The information in the report should be presented as clearly and concisely as possible. Imagine that you are writing a report that you would want to read. Imagine that you will have to make an important decision based on the information in the report.

The technical content in the report will not be efficiently transmitted if the report is disorganized or poorly written. Conversely, regardless of how well the prose is written, the report needs to be built upon sound engineering and provide concrete evidence to support the conclusions.

Writing well takes effort. Writing well takes practice. Writing well requires learning how to edit and revise your own writing. Therefore, it is wise to practice writing regularly. For a project like Capstone that spans several months, it is wise to continuously document your work as opposed to waiting until an approaching deadline. Get in the habit of writing small reports for yourself that document tasks as they are completed. Then, when the big report is due you will have prior work that you can edit and combine, instead of having to create a large first draft from scratch.

Capstone Reports

A Capstone project report is more complicated than a lab report or technical research paper. Capstone project documentation is expansive and contains many different file formats. Capstone project documentation also evolves as the team's knowledge of the design problem and its solution evolves.

Complex Documentation Formats

A major complication with Capstone reports is the scope and variety of documentation required to make a design transferable: CAD files, computer programs for control systems, assembly instructions, bill of materials, etc. Including all this information in a single, written report would make the document unwieldy and, therefore, defeat the purpose of efficiently conveying information to the client and other engineering teams. Furthermore, the digital CAD files and computer programs need to be made available in a format that engineers can easily reuse in continued development of the design.

Note that when we refer to a "written report" we mean a document that can be printed on letter-size paper.

To manage the scope and variety of information necessary to document a design, student teams create a digital archive to store information in different formats. At the end of the project, the digital archive is submitted on a USB (flash) drive. The written report includes an index to the material in the digital archive. Only select information from the archive, e.g. images from CAD files, a bill of materials, and diagrams of system components, are included in the written report.

Evolving Project Information

Another complication with Capstone documentation is that the information about the design changes as the design evolves. In some cases, the new documentation reaches different conclusions than the earlier documentation. There are two solutions to this complication. First, if later information builds upon and is consistent with earlier information, simply refer to the earlier documentation without necessarily using the same level of detail. For example, a summary of key client requirements would be included in the final report, and the reader would be referred to the details documented in an earlier report.

A second complication with evolving information is when the team has knowledge at a later stage that requires revision of work completed at an earlier stage. The best approach in this situation is to keep the early report in the digital archive and release an updated version. In subsequent reports, the team refers to most recent report.

General Report Writing Guidance

During class meeting 6, we'll have a presentation by William Nesbit on "Writing for Clarity". Mr. Nesbit is a writer, editor, and communications trainer with over 40-years of experience working with engineering companies, research organizations, corporations, and government agencies across the country.

Mr. Nesbit recommends these writing resources

The Elements of Style by William Strunk Jr. and E.B. White
A Writer's Reference by Diana Hacker and Nancy Sommers
thesaurus.com
The Owl (On-line Writing Lab) at Purdue University

The following sections provide general guidance for writing technical documentation. This guidance also applies to Capstone reports.

Purdue's OWL

The Purdue Online Writing Lab is an outstanding source of information on writing. If you have a question about the structure of documents, grammar, or citation of references, search OWL first. In particular, consider the following entry points to the OWL site.

Citation of Information not Created by the Team

All work of others – technical reports, images, data, equations, performance specifications, laboratory procedures, design documents – must be properly attributed to the source. The internet is an abundant source of information, and web browsers make it easy to copy text and images. Just because it is technically easy to copy from internet sources, do not use information from the internet without attribution.

For guidance on citations, refer to web sites by the American Society of Mechanical Engineers, the American Physical Society, the Institute of Electrical and Electronic Engineers, and the University of Pittsburgh Library.

ASME Guide to references
APS Example References
IEEE Style Manual
Pitt library guides on How to Reference Sources

Ethical and Professional Conduct

Appropriate citation of sources is an ethical responsibility of being an engineer. Refer to ASME's Ethical Standards for Authors. The basic ideas are to give credit where it is due, and not claim the work of others as your own.

In addition to the ethical obligation to cite prior work, engineers are responsible for the truthful and accurate reporting of results of analysis and experimentation. In its publication, On Being a Scientist, the National Academy of Engineering cite the U.S. Office of Science and Technology policy on behaviors that constitute research misconduct:

Fabrication is the "making up of data or results"

Falsification is "manipulating research materials, equipment, or processes, or changing or omitting data or results such that the research is not accurately" represented in the research record."

Plagiarism is "the appropriation of another person's ideas, processes, results, or words without giving appropriate credit"

All of these behaviors are to be avoided.

Tables and Figures

All tables and figures should have a number and caption. Captions for tables go above the table, as shown in Table 1, below. Captions for figures go below the figure, as shown in Figure 1, below

Software packages that create plots, e.g. Excel, R, MATLAB, provide the option of creating a plot title that is usually displayed above the plot axes. The plot title is not a caption. For a single plot frame, the title supplied by the software is usually redundant. When the figure is a composite of two or more plots, titles for individual plots are helpful.

Table 1: Dimensions of heat sinks. H, L and W are the height, length and width of the heat sink in inches. (Demonstration of a table caption.)

Demonstration table

Demonstration plot

Figure 2: Measured temperature rise versus power input: demonstration of a figure caption.

Equations

There are two ways of presenting equations in technical documentation: in-inline and displayed. An in-line equation flows with the rest of the text. For example, Einstein's famous equation is $e=mc^2$ . In-line equations can be used as a rhetorical device to aid reasoning, as shown in the following examples

The hydrostatic equation, $p = \rho g h$ , shows that the fluid pressure increases linearly with depth, $h$ , and does not depend on the volume of fluid.

From the formula for moment of inertia of a rectangular cross section, $I = \frac{1}{12}bh^3$ , the beam stiffness is significantly more influenced by changes to the beam depth, $h$ , than to changes to its width, $b$ .

In both of the preceding examples, the in-line equation adds precision and clarity to the sentence. It would be less efficient and more clumsy to attempt conveying the same information in words only.

A displayed equation occupies a separate line in the document. For example, using the displayed equation format, the Bernoulli Equation is

$\frac{p_1}{\gamma} + \frac{V_1^2}{2g} + z_1 = \frac{p_2}{\gamma} + \frac{V_2^2}{2g} + z_2 \tag{1}$

Displayed equations should be centered and have a right-justified, numerical label in parenthesis. Do not label equations with "Equation" or other text, as illustrated in Figure 2.

Incorrect equation tag

Figure 2: Only use numbers as equation labels.

Displayed equations are generally preferred over in-line equations, especially when documenting a calculation procedure or explaining analytical or experimental results. The use of equation numbers makes it easy to unambiguously refer to an equation. A displayed equation is also easier to find when scanning a document.

References

Institute of Medicine. 2009. On Being a Scientist: A Guide to Responsible Conduct in Research: Third Edition. Washington, DC: The National Academies Press. https://doi.org/10.17226/12192, p. 15

PDF version