We hope that writing work-term reports will help you develop your engineering judgment and your writing skills. (Also, work-term reports are required for our accreditation as a co-op university; this accreditation enhances the value of your eventual degree!)
A satisfactory report must explore an engineering decision (or a series of decisions) and justify a choice, either through a comparison with viable alternatives, or by showing how the selection meets a given set of constraints. Well-written text (as also found in a good version control pull request), combined with appropriate figures, is one of the best ways to justify an engineering decision, and serves as documentation for your successors.
Work-term reports should ideally:
- connect your co-op experiences with your academic curriculum;
- illustrate how something that you did was engineering, i.e. how it applied mathematically or scientifically determined knowledge (in the broadest sense) to solve a problem;
- discuss the impact of your work in the broader world; and
- show some self-reflection about what you have done and what you have learned.
An excellent report will be clear, concise and convincing. There exist awards for top work-term reports, sponsored by the Sandford Fleming Foundation and various companies.
Some thoughts about communication from Kate Matsudaira, in "Fresh Starts", Communications of the ACM. October 2016. Volume 59, Number 10: "[... ideas] for improving your working relationships:
- Improve your communication skills. When you get better at writing email messages, or verbal presentation, you help share information, and this creates better decision making across your whole team."
Report contents
Your work report must describe a design decision (or a series of related smaller decisions) and justify a choice. The justification may either be 1) that the solution is the best one among several viable alternatives, based on sound engineering judgment; or 2) that the solution indeed solves a constrained design problem.
A high-level view of your work report's structure is "context/contents/conclusion".
Provide enough context (including design constraints) to introduce the decision that you are considering. The main content explains the constraints and, if appropriate, the alternatives, including the strengths and weaknesses of each of the alternatives. Conclude by justifying your solution and discussing its impact. Include references as needed.
Here is a list of possible categories of work reports. This list is not exhaustive; contact the work-term report coordinator for clarifications. A work-term report may belong to several of these categories.
-
What I did last summer.An analysis of engineering problems that I solved. Why my boss is wrong.Proposal of a better solution to a real problem; your solution need not be implemented.Cool stuff I read about.Research paper summary/critique.
Your work report may focus on one larger decision, or it may describe a sequence of smaller decisions. Choosing smaller decisions allows you to explore how earlier decisions affect later ones. Each of the
decisions would have its own constraints.
Design under constraints is key to engineering, and your work report may focus on how your solution (or solutions) meets its constraints. Examples of constraints include: "X's maximum response time must not exceed 100ms" or "Y must be better than the status quo." We expect that you would define what "better" means (see below).
Alternately, you may focus on a comparison (or several of them). In a comparison, you will implicitly argue that your preferred alternative best meets constraints. A comparison may have the status quo as one of its alternatives. A comparison must not have a straw man as an alternative. It is your responsibility to convince the reader that the comparison is relevant to an actual problem that a real person has faced.
In all cases, we are looking for you to support your conclusion (that your design meets constraints, or is the best alternative) with technical rigour. Your justification may take several forms, including quantitative measurements, user stories, and proofs. We don't want "warm fuzzies" as a justification (i.e. this solution is better because I think it is); we're looking for stronger evidence than that.
Report non-contents
A work-term report should not be a tutorial (e.g., what is .NET and how does it enforce security). It should not be a user's manual, a marketing document, or any other company-related document that has been extended to be a work-term report. It should not be a chronological description of how you created a product. We are not looking for a comprehensive report of everything that you did on your work term; more specifically, we are not looking for quantity of accomplishments. What we are looking for is your ability to recognize, document, and explain a software engineering decision.
Report format
The main formatting criterion is that your work report must be readable and understandable. We encourage good page layout and reasonable font choices (e.g. 12 point text). LaTeX is an excellent choice for technical writing.
Work reports must be free of spelling mistakes. (Spell checkers exist; use them!) We encourage correct, clear, and concise English. However, we will mark your work report as long as we can understand it; good writing will get better marks than bad writing.
Your work report may be written as a traditional engineering report or in a more expository blog-post format (potentially on your own blog). Even if it is written in blog-post format, we still expect critical analysis.
Your work report should be around 2500 words, plus or minus 20%. That is around 5 pages in a reasonable single-spaced font. The word count excludes diagrams. We strongly encourage you to use diagrams when appropriate.
We require you to self-categorize work reports by topic, by providing a list of 1-3 courses in the curriculum that are most relevant to your work report. These courses includes those that you have taken already and courses you have not yet taken. This list helps us figure out who is best-qualified to mark your work report. Making this list helps you become more familiar with your curriculum.
Technical requirements
One of the most important instructions is that PDF is the only acceptable format for your submitted report.
Header block: Your work report must start with a report title and your name. Include the list of relevant courses (described above).
You may submit a work report that is a concatenation of one or more blog posts. If you do so, please export your posts to PDF for marking. Include the header block on a cover page. We do not impose any other formatting requirements.
Logistics
As a Software Engineering student, you must submit a work-term report at the start of your 2B, 3B, and 4A academic terms, regardless of your co-op employment status during the previous work term. Submit your report electronically on Waterloo LEARN. Look for your Work Term Report course, and for the drop box within there. Only your latest submission is retained; at any time, the prior submission is overwritten by the current submission.
Software Engineering work reports are due seven calendar days after the first day of lectures for the term. For example, if the first day of lectures is September 1, 2027, then the work term report is due on September 8, 2027.
A late submission will receive a failing mark, and will be marked during the following term. Normally, reports will be marked by four weeks before the end of the term of submission. You will be notified via e-mail when your report has been evaluated.
Confidential work reports
We recommend that you discuss your work-term report with your employer about half way into your work term. We do not keep copies of the reports nor do we allow our markers to do so. Of course, with your employer's permission, we encourage you to share your blog-format work reports as blog posts.
We recommend that (1) you strive to extract from your work-term experience some software-engineering problem that you had to solve, and that (2) you abstract or anonymize the problem and your solution, so that your report does not include any company confidential information. Our markers do not sign non-disclosure agreements (NDAs).
If these measures do not satisfy the employer, then in special cases the work term report coordinator may allow the report to be marked by the employer. Only one such employer-marked report is allowed per student.
To request that your report be marked by your employer, send the following information about the marker to the work report coordinator: marker's name, email, workplace, position and technical background. Usually the marker's LinkedIn profile is adequate for their technical background but if it is unavailable then describe their technical degrees and/or technical work experience. If the coordinator approves the marker, then they will send the marker instructions on the grading procedure.
Resources
An excellent discussion of design decisions that you may have made can be found in Butler Lampson's "Hints for Computer System Design". (Butler Lampson had a key role in the design of many of the systems that are ubiquitous today, including Ethernet and word processors.)
Here are some templates to help you get started (note that you're free to develop a layout and style that works best for your report content).
- LaTeX template (and resulting PDF)
- MS-Word template
And here's a To Do list so that you don't forget anything.
Conclusions
Our goal is that these work report guidelines will allow you to write about something you've done that you're proud of, and that they will allow you to think about an instance of engineering judgment.
Changes from previous versions
The core of the work report remains the same: you should describe an engineering decision, explain constraints, perhaps explore alternatives, and recommend a particular choice. We have made several changes around the margins. The most significant content-related change is that you are not required to make a quantitative comparison. (Quantitative comparisons are still acceptable, if appropriate to your topic). In terms of formatting, we've relaxed formatting requirements (note: no letter of submittal) and reduced the word limit. We hope that the required conciseness will encourage you to include only what is important.
Examples
There are no perfect examples of what we're looking for. Here are some examples of writing that is close to what we're looking for, and some explanations of how they fit our work report format.
All of Jamie Wong (SE 2014)'s blog entries are good, but some of them are more tutorial. This one is a clear comparison:
http://jamie-wong.com/bending-the-pl-curve/
Note that he provides clear examples to support different trade-offs.
In the following post, Jamie Wong shows self-reflection and critically evaluates the design decisions that he made.
http://jamie-wong.com/2014/01/03/travelmap/
Amit Patel has a vast number of game-related tutorials on the Internet. His tutorials are well-written; however, tutorials as such generally do not have enough analysis. In the following article, though, the author reflects on the choices he has made over the last five years, which is what we like to see in a work report. In the context of a work report, we discourage you from listing everything you have done in your work term; focus on a particular decision (or a series of related decisions) that you made.
http://simblob.blogspot.ca/2016/12/five-year-mission.html
"I realized at some point that my most successful pages were about problems that I had in a real project, and the least successful pages were about problems that I expected to have in a future project." (In your work report, you would include evidence to support such a statement, e.g. readership/engagement stats.)
The following entry from the Uber blog introduces the problem of forecasting demand for extreme events, explains their initial model (in not very much detail, but that's about right), motivates a need for an improvement, and explains and evaluates the improvement. (Comparisons in your work report can be vs. the status quo).
https://eng.uber.com/neural-networks/
Here is a Netflix tech blog article which describes how they handle input on non-standard devices (remote controls). They provide a lot of context, including the constraints they are working under, and support
their decisions.
https://medium.com/netflix-techblog/pass-the-remote-user-input-on-tv-devices-923f6920c9a8
From the compilers world, consider the following design discussion about a series of design decisions behind Chrome's V8 Javascript compiler. This work is guided by empirical constraints at every step; their goal is to achieve the fastest possible performance on realistic JavaScript code. And there is a good discussion of engineering constraints.
http://benediktmeurer.de/2017/03/01/v8-behind-the-scenes-february-edition/