Technical Writing Example I like Coffee Every Morning

Technical Writing Example I like Coffee! Every Morning when I get in to the Office I go to the Eng. Soc 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! Fall 2004 SE 101 Technical Report Presentation 1

What am I Going to Do? 1. Identify my criteria and their relative weightings • • 1. Cost - 1 ‘Fullness’ - 3 Calorie - 1 Taste - 2 1 is the least important and 3 is the most important. Fall 2004 SE 101 Technical Report Presentation 2

What am I Going to Do? 1. 2. Identify my options The C&D offers the following for breakfast: • Bagel • Muffin • Donut Fall 2004 SE 101 Technical Report Presentation 3

What am I Going to Do? 3. Analyze My Options I will run a the following experiments on my alternatives: • • Cost Analysis ‘Fullness’ Analysis Calorie Analysis Taste Analysis Fall 2004 SE 101 Technical Report Presentation 4

What am I Going to Do? 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 Fall 2004 SE 101 Technical Report Presentation 5

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! Fall 2004 SE 101 Technical Report Presentation 6

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 Fall 2004 SE 101 Technical Report Presentation 7

Example Title Page University of Waterloo Software Engineering An Analysis of Breakfast Foods in the Engineering Society Coffee and Donut Shop University of Waterloo, Ontario John Doe 2007#### 2 B October 22, 2003 Fall 2004 SE 101 Technical Report Presentation 8

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 Fall 2004 SE 101 Technical Report Presentation 9

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 Fall 2004 SE 101 Technical Report Presentation 10

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. Fall 2004 SE 101 Technical Report Presentation 11

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!!) Fall 2004 SE 101 Technical Report Presentation 12

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 Fall 2004 SE 101 Technical Report Presentation 13

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 Fall 2004 SE 101 Technical Report Presentation 14

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. ” Fall 2004 SE 101 Technical Report Presentation 15

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. Fall 2004 SE 101 Technical Report Presentation 16

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 Fall 2004 SE 101 Technical Report Presentation 17

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. Fall 2004 SE 101 Technical Report Presentation 18

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!!!) Fall 2004 SE 101 Technical Report Presentation 19

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. ” Fall 2004 SE 101 Technical Report Presentation 20

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. Fall 2004 SE 101 Technical Report Presentation 21

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. ” Fall 2004 SE 101 Technical Report Presentation 22

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. Fall 2004 SE 101 Technical Report Presentation 23

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 Section http: //www. computer. org/author/style/refer. htm NOTE: All URLs must have their access date. Fall 2004 SE 101 Technical Report Presentation 24

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!!) Fall 2004 SE 101 Technical Report Presentation 25

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. Fall 2004 SE 101 Technical Report Presentation 26

Draft Report Don’ts 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 Fall 2004 SE 101 Technical Report Presentation 27

Draft Report Don’ts 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). Fall 2004 SE 101 Technical Report Presentation 28

Draft Report Don’ts 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. Fall 2004 SE 101 Technical Report Presentation 29

Draft Report Don’ts 5. DON’T use a table in your table of contents ‘Nuff said! Fall 2004 SE 101 Technical Report Presentation 30

Draft Report Don’ts 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. Fall 2004 SE 101 Technical Report Presentation 31

Draft Report Don’ts 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. Fall 2004 SE 101 Technical Report Presentation 32

Draft Report Don’ts 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. Fall 2004 SE 101 Technical Report Presentation 33

Draft Report Don’ts 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? Fall 2004 SE 101 Technical Report Presentation 34

Draft Report Don’ts 10. DON’T have only two sections in the main body of your report (e. g. 1. Intro 2. Analysis) 11. 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. Fall 2004 SE 101 Technical Report Presentation 35