Technical Writing Example

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

2. What am I Going to Do? • 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. SE 101 Technical Report Presentation

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

4. 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 SE 101 Technical Report Presentation

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

26. Draft Report Don’ts • 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. SE 101 Technical Report Presentation

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

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

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

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

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

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

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

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

35. Draft Report Don’ts • 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. SE 101 Technical Report Presentation