Technical Writing Example

Fall 2004 SE 101 Technical Report Presentation

1

Technical Writing Example

I like Coffee!

Every Morning when I get in to the Office I go to the EngSoc C&D to get a cup of coffee.

Every morning I have to decide whether to get something to eat with my coffee.

Since I’m an intrepid engineering student and the SE 101 TA, why not use an engineering analysis to find out what I want to eat in the morning!


2

What am I Going to Do?

1. Identify my criteria and their relative weightings

• Cost - 1• ‘Fullness’ - 3• Calorie - 1• Taste - 2

1 is the least important and 3 is the most important.


3


2. Identify my options

The C&D offers the following for breakfast:

• Bagel

• Muffin

• Donut


4


3. Analyze My Options

I will run a the following experiments on my alternatives:

• Cost Analysis• ‘Fullness’ Analysis• Calorie Analysis• Taste Analysis


5


3. Make a Decision

I’ve decided I’m going to eat a bagel because:

• It is relatively cheap• It is small and not too filling• It is somewhat low in calories• It has a poor taste, but this is outweighed by the

above considerations


6

I’ve Reached A Decision

Using a brief version of the engineering design process, I was able to come to a decision.

Now, because I’m a stickler for detail, I’m going to write a formal Engineering Analysis Report conforming to the SE Work Report Guidelines on how I reached this decision so I can explain it to all the other WEEF TAs!


7

Title Page

Things I have to include on my title page:

• University and Program Name• My Report title• Name and Location of my Employer• My name and my student ID#• The previous Academic term I completed• The date I completed the report


8

Example Title Page

University of WaterlooSoftware Engineering

An Analysis of Breakfast Foods in the Engineering Society Coffee and Donut Shop

University of WaterlooWaterloo, Ontario

John Doe2007####

2B

October 22, 2003


9

Letter of Submittal

Things I have to include on my letter of submittal:

• Must be addressed to SE Program Director• Must mention the report title• Must mention my previous academic term• Must mention my employer and my department• Must mention what my department does• Must explain the report’s purpose• Must acknowledge any assistance I received• Must state who I wrote the report for• Must have the exact declaration statement from

the SE Work Report Guidelines• Must have my name, student ID, and signature

Microsoft Word Document


10

Contributions

This is where you can include who did what in your team and who did what in your subgroup.

Things I have to include in Contributions:

• Size of team working on the entire project• The team’s goals• What your tasks were• How this report relates to your tasks• How your work relates to your team’s goal


11

Example Contributions

“I was the sole member of the Breakfast Analysis team whose goal was to determine the best breakfast food option in the Engineering Society Coffee and Donut Shop (C&D). This report relates to my work as I would always buy coffee at the C&D every morning. This work is important because if WEEF TAs eat a proper breakfast they will have sufficient energy to teach their students.”

NOTE: A real contributions section will be 2-3 pages and be MUCH more detailed.


12

Executive Summary

The executive summary is a brief version of your report. Its purpose is to convey the basics of your report to a high level executive (e.g. the plant manager or a VP) so that they don’t have to read the entire report.

It should:• Explain the purpose and scope of the report• Highlight the major points in the report• Highlight the conclusions of the report• Highlight the recommendations of the report• Be 1-2 pages in length• Be less technical (VPs read it!!)


13

Other Front Matter Sections

Formatting for the Table of Contents, List of Figures, List of Tables are all clearly explained in the SE Work Report Guidelines and SE Work Report Checklist.

Guidelines:www.softeng.uwaterloo.ca/Current/work_report_guidelines.htm

Checklist:www.softeng.uwaterloo.ca/Current/WKRPT_checklist.pdf


14

Introduction

The Report Introduction needs to

• Explain the purpose of report• Inform the reader of the intended audience• Introduce your problem to the reader and the

motivation for the work that you’re doing• Give any background information not assumed

to be part of the reader’s knowledge base


15

Example Introduction

“This report analyses the breakfast food options available in Engineering Society Coffee and Donut Shop (C&D) and is intended to be read by Waterloo Engineering Endowment Fund (WEEF) teaching assistants (TAs) and any other interested breakfast shoppers. It is often the case that people are conflicted regarding what to buy with their coffee for breakfast. This report will analyze three breakfast options: bagels, muffins and donuts. The report will draw conclusions as to which breakfast option is the better choice.”


16

Analysis

The meat of the report goes here.

Explain what your possible solutions are. List their advantages and disadvantages using the results of the experiments you conducted.

DON’T just list your experiments! Use appendices to refer your experimental methods and cite these appendices when you explain how they support/dismiss your solutions.


17

Point-Form Analysis

Bagel• 55 cents, priced in the middle of the other two• Medium Size• Moderate Calories• Kind of bland taste in comparison to the others

Donut• 50 cents, cheapest option• Small• High Calories• Tastes Sweet and a little greasy


18

Point-Form Analysis

Muffin• 80 cents - most expensive option• Really Large• High Calories• Sweet Taste

Bagel seems to be the best option, even though it lacks in taste, as it is relatively inexpensive, is not to filling, and is comparatively low in calories.


19

Conclusions

This is where you highlight the solution/design you chose and briefly summarize how it successfully solves your problem and meets your requirements.

Should be about a page in length.

Should not introduce any new material. (This goes for the recommendations too!!!)


20

Conclusions

“The best option for breakfast food is a bagel. Due to the bagel’s low cost, moderate size, and comparatively low calories, it is the perfect breakfast food to eat with a morning coffee.”


21

Recommendations

Here you highlight what your group recommends as a solution in your situation. You can also recommend different solutions for situations that are slightly different from your own. You are also encouraged to state any changes you would have made to either your design or the project.

We are asking that you also touch upon the usefulness of the simulator in completing the project.

This section should be no more than a page.


22

Example Recommendations

“This report recommends that a bagel should be bought at the C&D as a standard breakfast with your coffee. If a bigger breakfast is desired, a muffin may be a better choice. If the customer desires a sweet tasting breakfast and is not concerned with calorie intake, then a donut would be the best choice.”


23

Conclusions vs. Recommendations

Note that conclusions and recommendations are very similar. The conclusions should state the direct results of the analysis (i.e. the bagel is the best choice). Recommendations should state what to do with that information (i.e. eat the bagel for breakfast everyday) and any further useful notes, as in the previous slide.


24

References

All references need to be in IEEE CS format. All references must be cited somewhere in the main body like this [#], where # is the reference number. The references should be ordered in the order in which they are cited in the main body.

IEEE CS Style Guide – References Sectionhttp://www.computer.org/author/style/refer.htm

NOTE: All URLs must have their access date.


25

References

This sentence is being referenced [1].

Hi, my name is Mr. Smith. This paragraph is being referenced. [2]

The authors of [3] indicate that…

In [4], the following equation is used:

The following is a bad style. [4] contains information… (never start a sentence with a symbol!!)


26

Draft Report Don’ts

1. DON’T use first person in the main body

First person is NOT considered appropriate for technical writing!

Just because you are writing in the third person does not mean that you have to write in the passive voice. Try to use as much active voice as possible by recasting sentences as necessary.


27


2. DON’T write the Letter of Submittal as a Memorandum

The Letter of Submittal is a letter and should follow proper business letter format. Look at Pg. 61 in the IPE for an example of letter format


28

3. DON’T talk about other subgroup’s design decisions in your subgroup’s report.

The report is meant to detail YOUR subgroup’s design decisions, not others. Only include information regarding other subgroup’s work if it is necessary information (e.g. if you are talking about integration decisions).



29

4. DON’T use Design Report as a title

Your title is supposed to give me an idea of what your report is about. Design Report tells me nothing about the topic or the content of your report.



30

5. DON’T use a table in your table of contents

‘Nuff said!



31

6. DON’T spell any names wrong, especially ours!

Spelling someone’s name wrong is a sign of disrespect. You don’t want to disrespect the person who is marking your report! Take some time and make sure all names are spelled properly.



32

7. DON’T insult the project

Why would we want to take your report seriously and give you a good grade if you are insulting the project you’re working on? You can constructively criticize aspects of the project, but make sure you don’t go overboard.



33

8. AVOID fancy report templates and graphics

Fancy templates tend to clutter your report and make it less readable. In my opinion, there’s nothing that looks more professional than a simple, properly formatted, page design.



34

9. DON’T use American spelling in your report

We live in Canada. Due this rather obvious fact, we expect you to use Canadian spelling throughout the report.

Ex:Color = COLOUR eh?



35

10. DON’T have only two sections in the main body of your report (e.g. 1. Intro 2. Analysis)

Split up your material into sections and subsections in such a way that it makes it easier for the reader to follow. Ideally, a reader should be able to look at the table of contents and understand the gist of the report.


Documents

Technical Writing Example