DesignWIKI

Fil Salustri's Design Site

Site Tools


design:reporting_guide

Reporting Guide

Effective communication is a key to being a good engineer. This is even more true in design, where there is less hard information (numbers, drawings, analyses…). How does one communicate a concept? These notes are intended to help you overcome typical difficulties in arranging and presenting material for your design projects.

Writing a report is like telling a story or explaining a mathematical derivation. It must be arranged so that each step is in order and explained well enough and with just enough (and no more) detail, so that the reader is led forward to the unavoidable conclusion of your work.

Questions to which you must have answers before writing a report are:

  1. What is the point of the work you are reporting?
  2. What is the goal of each chapter or section?
  3. What is the goal of each paragraph?

The "diamond"

Fig. 1: The document diamond.

Your written reports should follow the same patterns as those typically found in technical papers. Find any technical paper in a reasonable journal and study it for tone, presentation, grammatical structures, and so on. You can read my own papers online; some of them are quite good that way. Some of the rules of good technical writing that I've found useful are in this page.

The most important one, however, is “be organized.” That means creating a document or a presentation that flows well from the statement of the problem, through a description of your solution, to conclusions indicating why your solution is a good one. I've found one trick that helps keep a document or presentation organized is to model it on the shape of a diamond. At its top and bottom, a diamond is very small; it only gets thick in the middle.

“Huh?” you say.

At the beginning is an abstract or summary of the work; this should be no more than 500 words (about 1 page) and should accurately describe both the problem you are solving and your solution to it. It's small, like the top of the diamond. Obviously, there's room for no details at all in the abstract.

Then comes the introduction, which lays out the background and describes the problem in detail (but ONLY the problem). You should be able to accurately describe the problem you address in your report in some detail. The introduction would also include background material intended to let the reader understand why its an important problem to solve and why a good solution would be of general benefit. Its bigger than the abstract (maybe many pages), but not as big as the body of the document.

The next section is the body of the document, which details all the things you did to reach your solution plus a detailed description of the solution. This piece can actually consist of many sections; it's up to you how you want to divide it up. This is the biggest part of the document – the middle of the diamond.

After the body is a section discussing the solution, its suitability, recommendations for future modification and improvements, problems encountered, and so on. It is smaller than then body.

Finally, there is the conclusion, which is very small. It should essentially repeat the contents of the abstract, but emphasizing the key benefits of your solution too. This is the bottom tip of the diamond.

While this is the order of the report, it is not the order in which you should write the report.

  1. Start in the middle. Write the body first, because the body is the heart of the report. It's where you make all your arguments and present your results.
  2. Then, write the introduction; this is where you set up the problem that you have answered in the body.
  3. Next, write the discussion, in which you discuss the body of the report and clearly indicate how the work reported in the body answers the questions posed in the introduction.
  4. Then, you can write the abstract, which should be a summary of the entire report, including introduction, body, and discussion.
  5. Finally, you write the conclusions. You can think of the conclusions as a retelling of the abstract — a little longer and with more detail.

Indeed, one might even consider the very top tip of the diamond to represent the title of your report – in which case, the title would be the very last thing you write. This makes sense – the only time you're really in a good position to give your report a title is when the whole thing is finished.

Scripting your report

Another technique for laying out your reports is to “script” it. Scripting is rather the opposite of the classical technique of note-taking.

Since many people have never been taught how to take notes, here is a quick refresher.

Scripting is note-taking in reverse

To script a report, you run the note-taking process backwards, starting with short items and working your way to longer descriptions.

  • You begin by laying out the major section headings.
  • Then under each heading you write the key thoughts for that section.
    • Use just point form or short sentences — one point/sentence per key thought.
    • Rearrange the points to create a good rational argument, moving from one point to the next.
    • Using this technique, you can write a 50 page report as an outline in just a couple of pages.
    • Key thoughts do not include directions to yourself — like “Add reasons why aluminum was chosen here.”
      • Instead, actually put the reasons into your outline — like “Aluminum was chosen because it's rustproof and light, and we don't need to weld it.”
  • Laying out the outline in this way lets you see the report as a whole without drowning in details.
  • Adjust the outline until the whole thing flows smoothly.
  • Now, take each point and expand it into a paragraph or more, to fully explain that thought.
  • Finally, go back and edit for continuity and style, and you're done!

For example, say you have written the following key point:

“The basic design/build/test cycle first advances the design state then analyses it with respect to requirements, at every systems level.”

This could be expanded into the following paragraph:

“There are two major processes in an iterative design cycle: the progression from requirements through design to a design state, and the analysis of a specified design to determine its performance relative to requirements. This design, build, test cycle can be applied both at the level of the whole spacecraft, and at the level of a single subsystem. Spacecraft studies at the conceptual level may involve one or both of these processes, depending on the goals of the study.”

When you're scripting a paper, report, or thesis, you should make sure you start with the goals – the things you want to achieve in each chapter, section, and eventually, paragraph. And using the diamond, you want to start from the middle: the body of the work. Let's look at an example. Say you've laid out your thesis to contain the following chapters.

  1. Introduction
  2. Background / Literature Survey
  3. Actual Work Done
  4. Discussion and Conclusions

You're going to start with the body of the thesis, Chapter 3. Say your thesis involved studying the bending characteristics of implanted rods meant to stiffen upper leg bones (femurs) to help them heal when they break. You have conducted the experiments and found that the alignment of the rod inside the bone is a primary determinant of the strength of the bone after it has healed. This is the key issue you want to address in the body of your thesis. You would lay out the sections in Chapter 3 as follows:

  1. Introduction
  2. Background / Literature Survey
  3. Mechanical Properties of Femur Implants
    1. Experimental Setup
    2. Collected Data
    3. Interpretation of Results
  4. Discussion and Conclusions

Extended Point Form

This has its own page.

General formatting rules for written reports

These are the standard formating rules:

  • 12 point Times-Roman (or similar) font for text throughout
  • 1.5 line-spacing throughout
  • 1 inch margins all around
  • Page numbers in lower right corner of each page. Page numbering will start with ROMAN numerals at the Table of Contents, and will restart in ARABIC numerals with the Introduction. All material before the Table of Contents is unnumbered.
  • Headings will be numbered and in bold
  • Figures will be numbered sequentially throughout, with centred captions below the figure
  • Tables will be numbered sequentially throughout, with centred captions above the figure
  • Equations will be numbered sequentially throughout, with equation numbers right-justified
    • (This is easily done in typical word processing software by setting a right-justified tab at the extreme right margin.)
  • References must follow the ASME style.

The structure of design reports

The report should be written as a technical report targetted at upper management and technical staff, not a sales or marketing tool to convince prospective customers to “buy” your product. The goal of the report is to convince your management and client that your product is worth putting into production.

The report will contain the following sections:

  • Title Page: Including title of project, course number and name, team member names and student numbers, and team ID number.
  • Executive Summary: This summarizes the entire report. One page long, maximum. It's probably wise to leave writing this till the end, so that you know what to summarize. This will be on a separate page. (See also Writing a good abstract.)
    • It's an executive summary because executives will read it. They will need to know what the design problem was, what your design intervention (solution) is, and why its a good solution for that problem.
  • Table of Contents: the usual….
  • List of Figures: The number, title, and page number of each figure that is embedded in the text. This should include figures in appendices.
  • List of Tables: Same format as list of figures.
  • Introduction: Describe the nature of the problem, your team's vision statement and mission statement, and any background material that you think is pertinent. The goal is to convince the reader that the problem is important and worthy of your time.
  • Body: The body of the report may include many sections and will depend on what you're presenting and the particulars of the project and the course. Refer to the project report requirements for your course for more details.
  • Conclusions: A summary of the project, including possible areas where your design could be improved, and technical and scheduling problems you encountered during the design.
  • References: A list of other texts, papers, and sources of information that you used to carry out your design. For an example, refer to any of my publications and check the references/bibliography section at the end of any of the papers listed.
  • Appendices: Raw data, technical drawings, background info (e.g. web pages of parts or similar products) can all be added into appendices.

Hints for writing good reports

See writing samples for examples of actual, poorly written student texts, plus revised and improved versions for each example.

  • Prefer the 3rd person active voice when writing your report; avoid if possible the passive voice.
    • Don't write: “I carried out the analysis.”
    • Don't write: “An analysis was performed.”
      • An easy way to tell if you're using the passive voice is to imagine adding the “by zombies” after a verb. If the sentence still makes sense, you're using the passive voice. Don't be a passive voice zombie.
    • Write: “One team member (Salustri) carried out the analysis.”
      NOTE: Students often ask if they have to use 3rd person active voice all the time. This can be answered from a design thinking point of view. To ask if one must used the 3rd person active voice is to ask about the structure of a product (the report) that you are designing. Instead, think of the function that such structures must satisfy. In this case, the function is to communicate clearly what was done, why, how, and when it was done, and by whom it was done. So long as there is no doubt in the mind of the person reading the report as to the answers to this question, then it doesn't matter what structure is used. That is, use the structures that guarantee providing the necessary functions.
  • Write/say what you mean and mean what you write/say. Don't write “The level of difficulty of this component of the exercise was considered substantially greater than that of other components,” when you meant to say: “This was the hardest part of the project.”
  • Don't abuse pronouns and generic nouns; use technical names and proper nouns as much as possible.
    • Don't write: “Once it was complete, another part was examined and it was analyzed to see if it was better than the last one.”
    • Write: “Once the analysis was complete, another structural member was analyzed. The results of the analyses were compared by team members Smith and Jones. The entire team voted, based on the comparison, to pursue the first option.”
  • Avoid bald assertions. These are claims made that are not common (engineering) knowledge that you do not substantiate with evidence.
    • For instance: “Everyone cares about maintaining a tidy lawn.”
    • This is a claim that could be true - i.e., it isn't impossible - but is so unlikely to be true that it must be substantiated.
    • The existence of a single bald assertion in an argument is enough to invalidate all the argument's conclusions.
    • Similarly, a single bald assertion can undermine completely the appropriateness of a design intervention.
  • Lay out the document to clearly identify the problem BEFORE you write about the solution. If you don't, a reader will not understand why you're doing what you're doing.
  • Lay out the document top-down, rather than bottom-up. Add successive layers of detail. Start with a general overview of the concept, then discuss the systems needed to implement the concept, and then finally how the components of each system were designed.
  • Don't include reams of raw data in the body of the document; instead, put them in an appendix. You may wish to have a little of the data reproduced in the body, so that you can explain it.
  • Place figures and tables within the text, near where they are discussed.
  • Assume the reader has an engineering degree, but don't assume the reader knows anything about your project. So you don't have to define what a force is, or what plastic is.
  • Define all acronyms the first time they are used, and include all acronyms in a glossary section.
  • Define all symbols used in mathematical equations (if any) in a list of symbols.
  • Embed individual figures directly in the text of the report wherever possible, and as close as possible to where the text discusses the figure. Do not put figures in an appendix (except for CAD drawings). If the reader has to jump between the text and some figure at the back of the report, they will have a harder time comprehending the report.

Here's an excellent example of good composition, taken from an email message of November 2012, to solicit systems engineers to participate in an online survey as part of a student's doctoral research:

For organizations that execute contracts, the ability to capture contracts is key to survival. Organizations use proposals to capture contracts. In the proposal process, systems engineering is often utilized in a number of different ways, including defining the solution that will be offered to the customer.

A survey is being performed to assess the relationships between various systems engineering factors and proposal success. The survey focuses on systems engineering activities, regardless of whether the employees performing the work have titles that include the words “systems engineer”. The results of this survey analysis will allow organizations to focus on competencies related to factors that have been empirically demonstrated to lead to proposal success.

I am a Ph.D. candidate at the University of XYZ focused on determining the most advantageous use of systems engineering in proposal management. A key part of my research contribution is a statistical analysis of the results collected by this survey. By participating in this survey, you will be contributing to identifying critical success factors for winning contracts. Once the results of this research are published, you can compare the proposal management practices within your organization to the findings of this research and identify opportunities for improvement.

Proposal efforts that result in contract awards and proposal efforts that do not result in contract awards are both of interest. If you have knowledge of multiple proposal efforts, we welcome multiple responses, one response per proposal effort.

Three 25 dollar (USD) ABC.com gift certificates will be distributed to randomly selected respondents. All information provided will be kept strictly confidential….

Here's why this is such a well-composed piece of text:

  1. Look at the first paragraph. Starting from generalities, it takes the student only three sentences to drill down to the topic of his survey. This grounds his work solidly with respect to the overall enterprise of systems engineering practice, and makes it relevant to the target audience of potential participants.
  2. While the first paragraph sets the stage, the second paragraph details the nature and intent of the survey; this makes it immediately relevant to research; this assures potential participants that their involvement in the survey will not be a waste of their precious time.
  3. The third paragraph provides background about the researcher, to convince potential participants that the researcher is serious, enrolled in a legitimate program of good standing, and so on.
  4. The fourth paragraph provides a bit of “sugar” to sweeten the survey pot, and includes the legal boilerplate language that every such survey must include.

Here's a slightly more humorous reason to write carefully: you want to make sure you're saying the right thing to your audience.

stingblade.jpgFig. 2: A single comma can make a world of difference

Final oral presentation notes

Suits and ties are NOT required, but a clean, well-groomed appearance is an important part of being a professional engineer.

Make sure you stick to the time schedule. Your team will be cut off immediately if you run out of time.

The team should work together to make sure the overheads or powerpoint presentation is well-done; all team members must contribute to the preparation and delivery of the presentation.

The presentation should summarize your project in a professional and technical manner. You are NOT trying to sell your product.

Here are some hints for oral presentations:

  • Don't waste time reviewing the Design Roadmap, or the methods or tools you learned in the course; stay focussed on your team's design.
  • Don't read from your overheads during the presentation. The overheads should contain only key points, in BIG fonts. The overheads should allow the audience to quickly capture the essence of the point you're trying to make. You can also use these key points as memory triggers to help you remember what you want to say.
  • There's a difference between spoken language and written language. It's usually glaringly obvious when you've memorized something that you've written because you wrote it. It's better to have a script of point form ideas you want to communicate, and then make up the sentences you say orally.
  • Keep the number of overheads to a minimum – figure it takes 2-5 minutes to present one overhead.
  • Use the overheads to help your memory. Put keywords in the overheads that you can use to help remember what to say.
  • Don't read from a prepared script during the presentation. You can have notes or prompt cards to help you remember what to say (but the overheads can do the same thing if you're careful).
  • Don't talk to the overhead. Talk to your audience. Don't focus your attention on one person in the audience; every once in a while move your eyes around and look at other people too.
  • If you're nervous about looking people in the eyes when you talk, look at their noses or their foreheads. They won't be able to tell the difference.
  • When practicing your oral presentation, talk as loudly as you expect to in the actual oral. When you talk loudly, you talk more slowly. If you practice by speaking softly you'll think you have a 3 minute presentation – but when you speak loudly it will be 5 minutes long – and you run the risk of going over your time allotment.
  • Presentations are not like stand-up comedy. A good presentation can be entertaining without being silly.

In 2016, one MEC723 team developed a truly outstanding Google Slides presentation. You can see it here. Focus not on the design itself, but rather how it was presented:

  • Notice the size and colour of fonts from a human factors point of view.
  • Notice how little text is on the slides - use the text as memory aids to remind you what you have to say, as well as hitting only on the key points.
  • Notice the quality of the images.
  • Notice the quality of the animations.

Some links that may be of use in preparing your presentations include:

design/reporting_guide.txt · Last modified: 2020.04.05 13:05 by Fil Salustri