software engineering _ current students _ policies and guidelines _ work report guidelines

7/31/2019 Software Engineering _ Current Students _ Policies and Guidelines _ Work Report Guidelines

1/14

16/12 software engineering > current students > policies and guidelines > work report guidelines

ww.softeng.uwaterloo.ca/Current/work_report_guidelines.htm

Copyright 2001 University of Waterloo. All rights reserved.

software engineering > current students > policies and guidelines >

work report guidelines

introduction evaluation: technical content

report topics sophistication of the analysis or synthesis

confidential final mark

self-study reports clearing failed reports

report format references

evaluation: technical communication wkrpt coordinator

sample reports:example 1, example 2

1. introductionWe use work-term reports to evaluate both your engineering judgment and your writing skills. A

satisfactory report is one that (1) describes sound engineering judgment that you used to solve an

analysis problem or a synthesis (i.e., design) problem, and (2) is structured and written in such a

manner that your ideas and recommendations are clear, concise, and convincing. You are likely a

highly skilled software designer, architect, or analyst; but if you cannot communicate your ideas or

concerns effectively to others on your project team, or to your managers, then your ideas will not be

realized in the final product.

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

You should submit your report electronically on UW Learn -- http://learn.uwaterloo.ca/ . Look for your

Work Term Report course, and for the drop box within there. Only your latest submission is retained;any prior submissions are overwritten with the latest submission.

The deadline for submission is 11:59 PM, 7 days after the start of term. For example, if the term star

on Monday, Sept 12, 2050, the deadline for submission is 11:59 PM, Monday, Sept 19, 2050.

One of the most important instructions is that PDF is the only acceptable format for your report.

A late submission will receive a failing mark, and will be marked the following term. Normally, reports

will be marked four weeks before the end of the term. You will be notified via email when your report

ready to be picked up.

Each work-term report is evaluated based on three criteria: checklist, communication, and technical

content. Checklist marking determines whether the report adheres to the SE work-term-report formaTechnical-communication marking evaluates the writing in the report, with respect to structure, clarity

and grammar. Technical-content marking evaluates whether the report supports its ideas and

decisions with sound engineering judgment. There are awards for top work-term reports, which are

sponsored by the Sandford Fleming Foundation and various companies.

This document describes the requirements for work-term reports submitted by Software Engineering

students. It borrows from the E&CE Work Term Report Guidelines [1] ) and the Faculty of

Mathematics Work Report Guidelines [2] ). Co-operative Education and Career Services produces

booklet , which describes the policies and regulations that apply to students enrolled in co-op

education programs, and which includes a chapter on work-term-report guidelines. This document

supersedes these other documents, with respect to guidelines and requirements for Software

-


2/14



.

The rest of this document is organized as follows. Section 2 discusses appropriate report topics, wit

an emphasis on the contents of, and the differences between, analysis and synthesis reports. Sectio

3 discusses confidential reports and self-study reports. Section 4 presents the formatting

requirements for SE work-term reports. Section 5 describes how technical-communication markers

evaluate reports, and summarizes the possible outcomes of technical-communication marking.

Section 6 describes our expectations regarding the technical content of SE work-term reports, and

how these expectations change as you progress through the program. It also summarizes the

possible outcomes of technical-content marking. Section 7 concludes this document by explaining

how final marks are assigned.

2. report topicA software-engineering work-term report is a technical document that describes an analysis of a

software-engineering problem or a design solution. A software-engineering problem is a software-

related problem in a specific context. For example, the following problems, often phrased as "Which

is better" problems, are context free and are therefore unacceptable report topics:

C verses Java

32-bit computing verses 64-bit computing

MS SQL Server verses MySQL

Algorithm A verses algorithm B

To be considered software-engineering problems, these questions need to be considered in the

context of a particular application, accounting for factors such as the type of data being processed,

the target computing resources, the skills of the development team, and so on. For example, whethe

C is the better choice of programming language than Java depends on several factors. Is the

application a device driver or a financial application? Does system performance or programmer

productivity have higher priority? What distinguishes a software-engineering problem from a genera

software-related problem is the context in which the solution will be developed or deployed. The

following variations of the above problems are acceptable report topics that were chosen by student

in previous terms:

Which language should be used for the Internet communications project?Should the next-generation ice-modelling algorithms be implemented on 32- or 64-bit

computers?

Which database should be used for organizing Orientation Week?

Which encoding method, Fourier or wavelet, should be used for edge detection in tracking an

image?

In general, a software-engineering problem's context describes the environment in which the softwar

will be developed or deployed. The context includes design constraints , which distinguish between

acceptable and unacceptable solutions (e.g., the software must run on a Mac OS platform, the proje

must be completed within 100 days, the software module must integrate into existing code,

responses to input must be within 2 seconds). The context also includes design criteria , which areproperties that discriminate better solutions from worse solutions (e.g., maintainability of the softwar

ease of use, cost of development, time to market). A recommended solution must satisfy all of the

design constraints. It should also optimize as many of the design criteria as possible. Thus, the

design criteria can be used to compare among acceptable solutions.

A work-term report can be either an analysis or a synthesis report, and it usually pertains to a specif

software-engineering problem that you encountered on your work term. Both types of reports follow a

similar outline: (1) a description of the problem , (2) a description of your solution to the problem, and

(3) justifications of the decisions or recommendations that you made in the course of deriving your

solution. For example, an analysis report describes an in-depth investigation of a software-

engineering problem, or of a software-engineering decision to be made. It includes the following

information:


3/14



1. Problem: A choice to be made among alternatives (e.g., a choice between using C or Java o

a specific project), or an analysis of an existing problem (e.g., an evaluation of the speedup

realized by the hotspot optimization in a specific Sun Java interpreter). The description

includes the context of the problem (e.g., the application domain, the background of the proje

team, the environment in which the final product will be placed) and the design constraints an

design criteria that are used to evaluate choices.

2. Solution: Your recommendations.

3. Justification: The data on which you based your recommendations. The justification includes comparison preferably a quantitative comparison of alternatives with respect to the specific

problem and the particular usage.

In contrast, a synthesis report describes design work. It includes the following information:

1. Problem: A summary of a requirement that is not being met, a problem that needs to be

solved, or a product to be developed. The description of the problem includes functionality or

services that the solution should provide, as well as the design constraints and design criteria

for evaluating and deciding among proposed solutions.

2. Solution: Your recommended design or solution.

3. Justification: An explanation of how your design or solution satisfies the need or solves the

problem. The justification includes alternative solutions that were considered and explains whthe proposed design or solution is the best fit with respect to the design constraints and the

design criteria.

In the above, "justification" does not mean trying to persuade the reader to accept your solution or

your recommendations. Your justification, and your report in general, should be a professional and

objective description of the decisions you made and the data on which you made your decisions. In

this respect, "professionalism" and "ethical reporting" is about fully disclosing all data available to

you, whether or not the data support your decisions or recommendations. Much of engineering work

is about using judgment to make decisions or recommendations in the presence of incomplete

information or conflicting goals. In such cases, a report's justification might include the assumptions

you made regarding incomplete knowledge; or it might include a trade-off analysis that assesses the

degree to which different alternatives satisfy various goals, and the relative importance of those

goals.

A work-term report should not read like a tutorial (e.g., what is .NET and how does it enforce security

It should not read like 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

design or software-engineering decision.

Confidential Reports

We recommend that you discuss your work-term report with your employer about half way into your

work term. Every SE work-term report is read by two markers: a technical-communication marker an

a technical-content marker. Once marked, the reports are returned to the students. We do not take

copies of the reports nor do we allow our markers to do so. If an employer is concerned about

confidentiality the reports can be placed in envelopes marked "SE-confidential" when they are

passed among markers. In that way, the markers know to handle the reports' contents carefully. As

such, 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 SE work term report


4/14



coordinator may allow the report to be marked by the employer. In these cases the marker should be

a professional engineer and only one such employer-marked report is allowed per student.

Self-study Reports

If your work-term experience is not a good basis for a work-term report, you may choose to submit a

self-study report on a topic, of your choice, that is related to a specific software-engineering problem

The structure and content of a self-study report is similar to that of a regular work-term report, in that

can be an analysis or synthesis report. It describes (1) a problem and the context, constraints, and

acceptance criteria of the problem; (2) your solution to the problem; and (3) the justification for your

solution. The only difference between a regular work-term report and a self-study report is in the letteof submittal: the author of a regular report would describe how the report topic relates to the author's

work-term experience, whereas the author of a self-study would describe the report as a self-study

report. A student may submit at most one self-study report during his or her academic career.

3. report formatIIn general, there is no single standardized format for software-related technical reports. However,

many businesses establish company-wide standards for structuring documents. Such standards hel

the author to ensure that his or her document is complete, and help the reader to find information

within the document quickly.

The following guidelines, expressed also in the SE Work-term-report Checklist , specify the formattin

standards that Software Engineering students follow when writing work-term reports. The checklist isnot a comprehensive list of all the requirements for your report's structure and contents. Rather, it is a

list of formatting requirements that, taken together, help to ensure that your report looks professional

and is easy to use as a reference document. The checklist requirements enable the communication

marker to determine objectively whether a report meets the formatting requirements.

Report Structure

A work-term report is made up of three parts: front matter, main body, back matter. The front matter

the report consists of all the pages that precede the report's introduction. It includes the front cover,

the title page, the letter of submittal, the executive summary, the table of contents, and the lists of

figures and tables, laid out that order:

CoversThe report is bound, with a clear plastic front cover (so that the Title Page can double as the front

cover) and a dark coloured (e.g., navy, maroon, black) opaque back cover.

Title Page

The Title Page contains the following information: university and program names, title of report, nam

and location of employer, student's name, student's id number, student's userid, student's previous

academic term, completion date of report, and SE-confidential if a confidential report . Here's an

example:

UNIVERSITY OF WATERLOO

Software Engineering

Data Structures for Modelling and Analyzing State-Machine Executions


5/14



Verisoft, Inc.

Waterloo, ON N2L 3T8

Prepared by

Sally Niu

Student ID: 12345678

Userid: [email protected]

3A Software Engineering

September 13, 2005

Letter of Submittal (Cover letter)

The Letter of Submittal resembles a letter that, in a work setting, would accompany the report when

is sent to a client, or to whomever requested the work being reported. We require that the Letter of

Submittal be inserted into your report, so that it does not become separated from the report during

marking. The Letter of Submittal is in standard business-letter format, as described in [3] , and is

addressed to the Director of the Software Engineering Program. It contains the following information

in the following order:

SE-confidential if a confidential report

Report title

Report number

Your previous academic term

Name of employer

Department(s) you worked for

Description of your co-op job (1-3 sentences)

Description of the report topic and how it relates to your co-op job (1-3 sentences)

Acknowledgement of assistance

Declaration statement of the form I hereby confirm that I have received no help, other than wha

is mentioned above, in writing this report. I also confirm this report has not been previously

submitted for academic credit at this or any other academic institution.

Student's name, student id, and signature

Here is an example, adapted from the ECE Work-term report guidelines [1] :

home_address

September 13, 2005


6/14



director_of_SE, Director

Software Engineering

University of Waterloo

Waterloo, ON N2L 3G1

Dear Madam (or Sir):

This report, entitled "Data Structures for Modelling and Analyzing State-Machine Executions," is my

first work-term report. It is based on my 2A co-op experience, working for Verisoft, Inc.

Verisoft produces software tools that semi-automatically verify properties of state-machine models o

software systems. I was employed in the Research Department, which is responsible for extending

these tools to work with new modelling notations. During the course of my co-op employment, I

helped to design, implement, and test a version of Verisoft's model-exploration tool to work with a

modelling notation used by one of Verisoft's customers.

This report analyzes different data-structure designs for representing a state-machine model, and

investigates the space and time complexity of these designs with respect to operations performed

on the model during verification. This analysis problem is similar to one that I encountered on my

work term. However, the data-structure designs and verification operations described in this report

have been modified from those with which I worked, to protect proprietary design decisions.

I would like to thank my supervisor, Dr. Marsha Checkik, for helping me to understand automated

verification, and for providing valuable advice and resources. I also wish to thank Mr. Patrice

Godefroid for proofreading my report and improving its appearance. I hereby confirm that I received

no help, other than what is mentioned above, in writing this report. I also confirm that this report has

not been previously submitted for academic credit at this or any other academic institution.

Sincerely,

signature

Sally Niu

Student ID: 12345678

Table of Contents

The Table of Contents appears on a separate page and contains an entry for each report-body

section and subsection, each item in the front matter (except for the Title Page and the Letter ofSubmittal ), and each item in the back matter. The entry titles of numbered entries (e.g., report

sections, appendices) include the entry numbers. Entry titles are left justified, indented per section

level (i.e., subsections indented within sections), and dot-filled to the corresponding page number,

which is right justified. Here is an example:

Table of Contents


7/14



ag

Executive Summary.................................................................................................................

Table of Contents.....................................................................................................................

List of Figures........................................................................................................................

List of Tables...........................................................................................................................

1. Introduction.........................................................................................................................

2. Automated Verification.........................................................................................................

3. Data Structures for Modelling State Machines........................................................................

4. Performance Analysis..........................................................................................................

4.1 Space Complexity.......................................................................................................

4.2 Time Complexity........................................................................................................1

5. Conclusions.......................................................................................................................1

6. Recommendations..............................................................................................................1

Acknowledgements.................................................................................................................1

References.............................................................................................................................1

Glossary................................................................................................................................17

Appendix A - Detailed Space Complexity Analysis.....................................................................1

Appendix B - Detailed Time Complexity Analysis.......................................................................2

iv

List of Figures

The List of Figures , if applicable, appears on a separate page and contains an entry for each figure

that appears in the main body of the report or in an appendix. There is no minimum or maximum

number of figures required for the report. Rather, the technical-content marker will evaluate whether

the report's information is represented appropriately in figures, in tables, or as text. The List of

Figures' entry titles are left justified and dot-filled to the corresponding page number, which is right

justified.

List of Tables

The List of Tables , if applicable, appears on a separate page and contains an entry for each table

that appears in the main body of the report or in an appendix. There is no minimum or maximum

number of tables required for the report. Rather, the technical-content marker will evaluate whether th

report's information is represented appropriately in figures, in tables, or as text. The List of Tables'

entry titles are left justified and dot-filled to the corresponding page number, which is right justified.

The main body of the report consists of the introduction, the sections and subsections of the report,

the conclusions, and the recommendations. The length of the main body is between 10 and 20 pagelong. The main body is divided into numbered sections and subsections. Information about the

contents of these sections is found in the Technical Content section of these guidelines.

The back matter of the report consists of all the pages that follow the report's recommendations

section, including the references, acknowledgements, and optional glossaries and appendices.

Information about the contents of these sections is found in the Technical Content section of these

guidelines.

References

The References section is used in lieu of footnote or endnote references. It contains at least three

references, and these references are cited in the main body of the report. References are listed eith


8/14



in alphabetic order of the first author's last name or in order of citation within the report. Each

reference is in a standard IEEE format and includes sufficient detail for a reader to contact the

publisher and obtain a copy of the referenced material. At a minimum, an electronic reference

includes the author, title, a URL, and the date (the current-as-of date ) when you last accessed the

document. Each reference is cited (referred to by number) in the report body text. No references are

cited in the report's front matter.

Appendices

Each appendix starts on a separate page. If an appendix cites referenced material, the

corresponding reference appears in a special References section at the end of that appendix. Each

appendix is cited (referred to by letter) in the report body text.

General formatting

The report is bound with a clear plastic front cover and a dark coloured (e.g., navy, maroon,

black) back cover.

The pages are of size 8 1/2 x 11 inches, with 1-inch margins.

Double-sided printing is accepted for all parts except the title page, letter and executive

summary. The main body should start on a right-hand page.

The text is in 12-point Times New Roman font, with 1.5 spacing.

Sections and subsection headings are numbered (e.g., 2.1, 2.2, ...), and are in decreasing-

sized fonts (e.g., 16-pt section headings, 14-pt subsection headings, 12-pt sub subsectionheadings).

Appendices restart the section numbering, using capital letters as section labels and Arabic

numerals as subsection labels (i.e., A.1, A.2, ); appendix

headers are in decreasing-sized fonts.

If a section is divided into subsections, it has at least two subsections. Similarly for

subsections divided into sub subsections, and so on.

The front matter, Conclusions, Recommendations, Glossary, Acknowledgements, and

References sections are not divided into subsections.

Each figure has a number and a caption below the figure.

Each table has a number and a title above the table.

Figure and table numbering restarts at the beginning of each appendix, using a combination

the appendix label and figure/table number within the appendix (e.g., A-1, A-2).Each figure and table is ci ted (referred to by number) in the report text, either on the same

page as the figure/table or on the preceding page.

Figures and tables are legible.

Paragraphs are indented, with one space between paragraphs.

Front-matter pages are numbered using lower-case roman numerals, with the title page as

page 1. Page numbers do not appear on either the title page or the letter of submittal.

Page numbering restarts at the main body of the report: pages in the main body and back

matter, including appendices, are numbered using Arabic numerals, with the first page of the

Introduction as page one. Alternatively, page numbering could restart with each appendix

where page numbers are prefixed with appendix letters (e.g. A-1, A-2)

Page numbers are centred at the bottom of the page.

Paper sections are correctly ordered.The length of the report's main body is 10-20 pages.

Checklist Marking

In checklist marking, a submitted report is checked against the formatting requirements listed above

These formatting requirements will be checked by the communication markers as part of the overall

communication mark for the report. No separate checklist mark will be given. However, reports that

do not follow the formatting requirements will have degraded communication marks.

4. technical communicationTechnical communication pertains to the effective communication of technical information. The


9/14



technical-communication marker evaluates the quality of communication in a report, with respect to

three criteria: the report's structure and flow, its clarity, and its writing.

The report's structure and flow pertains to how well information and ideas are organized and

presented. Introduce the problem being reported clearly, and explain why the problem is important

and interesting. Provide sufficient background material, draw conclusions, and make

recommendations at appropriate points in the report's main body. Structure the report's sections and

subsections to guide the reader effectively through the work being reported. As appropriate, use

figures and pictures to simplify and clarify descriptions, use tables to organize and relate data, and

use graphs to summarize trends in data; do not present raw data in the body of the report. Ensure th

figures and tables are self contained, and use captions (figures), legends (tables or graphs), and axiannotations (tables or graphs) to convey explanatory information. Relegate complex detai ls to

appendices, glossaries, or cited references.

The report's clarity pertains to how clearly information and ideas are expressed. Keep your

descriptions concise, and present explanations in a logic order. Choose your words carefully and us

them correctly. Ensure that the report's conclusions and recommendations follow from either the

analytical results or the synthesis. At the technical-communication stage, evaluations of the

conclusions and recommendations are made from a communications standpoint rather than a

technical standpoint.

The report's writing pertains to technical aspects of the writing. Use formal and standard English with

no contractions. Check that your report is free of spelling errors, grammar and punctuation errors,

slang, colloquialisms, sentence fragments, and run-on sentences. Use Canadian spelling. Define, on

first use, all technical terms and acronyms. Ensure that your writing is objective and professional in

tone, and not pretentious, persuasive, or defensive. Use paragraph and sentence structures that are

appropriate to a university student at your level in the program.

There is no constraint on the voice (first person, third person) used in the report. Technical reports ar

often written in the third person and in a passive voice, to emphasize the work rather than the author

or the workers. However, such writing tends to be cumbersome and wordy. We recommend writing i

the active voice, to improve the clarity of your writing. We recommend writing in the third person (e.g

"the team", "the software architect") over the first person (e.g., "I", "we"), to de-emphasize who is

performing or reporting on the work. However, first person is acceptable, as long as the tone of the

report is professional rather than personal.

Technical-Communication Marking

A report's technical communication is normally evaluated by a marker from the English department

(e.g., a graduate student). For each of the four evaluation criteria -- format requirements, structure an

flow, clarity, and writing -- the marker assigns a numerical value between 0 and 3 that indicates the

degree to which the report meets that criterion. The interpretations of the assigned values are Mostly

(3), Marginally (2), Slightly (1), and Not (0). The report's technical-communication score, then, is

calculated by summing the numerical evaluations for format requirements, structure and flow, clarity,

and writing , for a maximum score of 12. A technical communication mark of 5 or less is evaluated a

unacceptable.

5. technical contentThe technical content of a software-engineering work-term report is the recognition, documentation,

explanation, and justification of a software-engineering design or decision. The following guidelines

provide details on what information is expected in various sections of the report. These guidelines a

followed by a subsection that discusses how standards for evaluating technical content correspond t

your level in the program. A second subsection describes the logistics of technical-content marking.

Executive Summary

The Executive Summary is a one-page summary of the report's highlights, including the purpose and

scope of the report, the major points in the report, highlights of the conclusions, and highlights of the

recommendations. It is self contained, and is meant to be read and understood by someone (e.g., a


10/14



company executive officer) who is not likely to read the report itself.

Introduction

The Introduction introduces the problem being studied, specifies its scope and context (e.g., how it

relates to other problems or subsystems), and identifies the design constraints and criteria used to

define "success." It also describes the report's intended audience, especially with respect to what

fundamental knowledge the reader is expected to have (e.g., with respect to mathematical or

programming knowledge), and it succinctly presents any background material that the reader needs

to know, to understand the rest of the report (e.g., information about the application domain). It

concludes with an outline of the rest of the report. Normally, a work-term report's introduction is no

more than two pages, so it is important to cover all of this information succinctly.

Main (Analysis or Synthesis) Sections

The Main Sections of the report are the heart of the report, containing detailed descriptions of the

technical decision being reported. In an analysis report, the Main Sections start by elaborating on th

problem identified in the Introduction , expanding on the problem definition and on background

material relevant to understanding the problem. They describe the analytical study or the experiment

performed, and explicate and justify any assumptions made. They conclude by reporting the results o

the study, drawing conclusions, and making recommendations. To be complete, an analysis report

should identify any threats to the validity of the analysis' results, and should describe the costs and

consequences of following, and of not following, the recommendations. In a synthesis report, the Mai

Sections start by elaborating on the problem identified in the Introduction, expanding on the problemdefinition to include rigorous and precise specifications of the design criteria and constraints. The

sections describe your solution to the problem, including an explanation of how your solution satisfie

the design criteria and constraints. They also report alternative designs and solutions that were

considered, and they explain why the proposed solution is most favourable in the given context. To b

complete, a synthesis report should identify any limitations of the solution proposed.

Conclusions

The Conclusions section clearly states to what degree the original problem has been solved.

Conclusions are explicitly stated; do not ask the reader to draw his or her own conclusions based on

your results. The section includes summaries of the conclusions drawn from report's analysis or

synthesis and includes limitations on the results. It does not introduce new conclusions that were not

mentioned in Main Sections of the report.

Recommendations

The Recommendations section clearly summarizes your recommendations for any actions to be

taken (e.g., allocation of capital or human resources) as the result of your report's findings. The

discussion may include recommendations as to who should perform these actions; the cost, timing,

and consequences of the recommended actions; and any side effects. The Recommendations

section can also state under which conditions you would give an alternative recommendation. Your

recommendations must be based on the results of the report's synthesis or analysis, and must be

explicitly stated; do not ask the reader to infer his or her own recommendations. Your

recommendations should not include proposals for future studies unless the report's results are

inconclusive (e.g., none of the solutions meet all of the design criteria, or multiple solutions do so). In

such a case, this section might recommend future analyses to be performed, to better differentiateamong indistinguishable solutions.

References

The References section clearly identifies the sources of all quotations, paraphrases, borrowed ideas

and technical data used in the report. A report that fails to identify such sources is deemed

Unacceptable , and the student may be charged with plagiarism .

Acknowledgements

The Acknowledgements section recognizes the people who helped with the writing of the work repor

yet whose contributions were not so significant as to warrant the helper(s) being named as co-

authors. This includes anyone who was interviewed, anyone who proofread the report, or anyone


11/14



.

Glossary

Avoid using highly technical terms and acronyms, so that your report is easily read and understood b

the reader (marker), who is not likely to be as knowledgeable about the details of your work as you

are. If multiple technical terms and acronyms are absolutely necessary, then define and explain them

adequately in the text, and collect their definitions into a Glossary for easy reference.

Appendices

The Appendices contain information that is either too distracting or too long to include in the report

text. In particular, relegate to appendices any supporting material or data that is not likely to be ofinterest to most readers, but which is necessary to evaluate or replicate your work. Such information

includes code, documentation for code, specifications, tables of data that are summarized or

presented graphically in the report's main body, test suites, and long mathematical derivations or

proofs.

Sophistication of the Analysis or Synthesis

We ask you to write four reports: two that correspond to your first two work-term experiences, and tw

that relate to your senior work-term experiences. The first two reports come early in your academic

career, so that we can give you early feedback on your technical writing, as these skills are often the

determinant factor when a potential employer decides to offer you a job. We ask for the two senior-

level reports because these latter experiences better resemble the types of engineering work about

which you are likely to write once you graduate.

The report's analyses and justifications must be commensurate with your level in the program. As a

second-year student, you may use qualitative analysis (e.g., "algorithm A is faster than algorithm B",

"tool X is better than tool Y because it has feature Z"), although quantitative analysis is preferred.

Either way, your analysis must be with respect to the problem's design criteria. For example, if a

feature Z is not relevant to the problem, then is a tool X that supports feature Z any better than a tool

that does not? If tool X has feature Z and tool Y has feature W, which tool is more appropriate to the

solution? If a tool is missing a critical feature, does it have a work around?

As a third- or fourth-year student, your report must contain quantitative evaluations (e.g., "algorithm A

is twice as fast as algorithm B"), and the conclusions and recommendations must be sufficiently

concrete that a manager could act on them. A senior-level analysis report should provide sufficientdetail for the reader to make a business decision. A senior-level synthesis report should be complete

enough to convince the reader (a manager) to allocate resources to implement the proposed design

Consider the following two examples:

Example 1. "Algorithm A has a run-time performance ofn3, for data of size n, whereas algorithm B

has a run-time performance of 100n2logn." It is naive to use only these complexity results to conclud

that algorithm B is better than algorithm A, as there may be a number of factors that justify the use of

algorithm A, including 1) n is known to be small, such as less than 200; 2) the algorithm's complexity

does not the determine the application's overall complexity; and 3) algorithm A is already

implemented and thoroughly tested.

Example 2. Application A is 2.5 times faster and has many more features than the currently used

application B. It is naive to use only these observations to conclude that A is the better application, a

there may be a number of reasons for staying with application B, such as 1) it would be cheaper to

purchase a new faster computer; 2) the 'additional features' are not expected to be used and are

therefore irrelevant; 3) the system has already been integrated with application B, and switching

applications could result in significant downtime; 4) none of the technical staff are currently trained in

application B, and the training budget is limited; and 5) the support and licensing agreements may b

different for the two applications.

In both of these examples, a decision cannot be made without at least approximate costs for each

factor involved. To make a decision in example 1, you might need to know


12/14



. ,

you may need to assume that n could be arbitrarily large.

2) How the complexities of algorithms A and B compare with the complexity of the host application.

3) How long it would take to implement and test algorithm B, and how much this development would

cost.

To make a decision in example 2, you might need to know

1) How much it would cost to purchase, install, and maintain a new computer. (This may include

training costs.)

2) What the additional features are, and whether they would help to solve other pressing problems.Would the use of these features improve productivity?

3) How long it would take to install the new application, and how much the downtime could be

minimized. What is the worst case scenario?

4) What the approximate training costs would be.

5) What the relevant support and licensing costs would be.

How you choose the factors on which to base your decision depends on the problem's design

constraints and design criteria. The requirements on an algorithm used in a critical real-time

application would be significantly different from the requirements on an algorithm used in an

interactive dialogue with a user. You may want to review the basic decision-making techniques

described in your SE 101 text, Introduction to Professional Engineering in Canada [3] .

Some senior work report reports might deal with software engineering principles that do not lendthemselves to quantitative analysis. In this case, Multi-Criteria Decision Making (MCDM), from the

management sciences could be used as a systematic way to evaluate qualitative results. Please se

the sample work report (example) for a good example of MCDM's application and some references

for further reading.

In summary, junior-level reports must evaluate their analyses or designs with respect to the design

constraints and design criteria of the problem. Senior-level reports must go further, performing

quantitative evaluations with respect to the problem's design constraints and criteria and providing

sufficient information to support the recommendations made in the report.

Technical-Content Marking

Normally, graduate students mark the technical content of a work-report.

The technical content of a work-term report is evaluated on a scale of 0 to 4, based on the following

criteria:

The topic has sufficient scope and depth to justify a report.

The writing displays evidence of sound engineering judgment, analysis or synthesis, and

insight appropriate to a university student at your level in the program.

The technical details appear to be correct and to form a coherent design or software-

engineering decision.

The meanings of the technical-content-marking scores are Yes (4), Mostly (3), Marginally (2), Slightly

(1), and Not (0). A report with a technical-content score of 0 is deemed Unacceptable and receives failing mark.

The technical-content marking of your report will include a Critical Feedback section, where the

technical-content marker can provide constructive comments on how to improve your skills in

communicating technical and engineering ideas.


13/14



6. final markFirst and second year work report grades are calculated using a combination of the reports'

technical-communication and technical-content scores. This evaluation is then translated into a

numerical mark. Reports are evaluated as follows, where the final evaluation is the table entry that

corresponds to the row that matches the technical-communication score and the column that matche

the technical-content score.

TechnicalCommunication

Technical Content

... 0 1 2 3 4

0-5 Unacceptable Unacceptable Unacceptable Unacceptable Unacceptable

6-8 Unacceptable Resubmit Satisfactory Satisfactory Very Good

9-11 Unacceptable Satisfactory Satisfactory Very Good Excellent

12 Unacceptable Satisfactory Very Good Excellent Outstanding

Students will be notified by e-mail when their reports are finished being marked and ready to be

picked up. If you receive a grade of Resubmit, you will have UNTIL THE DAY BEFORE THE START

OF THAT TERM'S FINAL EXAMS to resubmit your report. If you miss this deadline, your report will

receive a mark of Unacceptable. A report may be resubmitted only ONCE. The resubmitted report isevaluated using the same table above. A mark of Unacceptable is a failed report. Failed work-term

reports are included in the failure count and must be cleared before graduation.

A report's final evaluation is translated into a numerical mark:

Evaluation Mark

Outstanding 95

Excellent 89

Very Good 75

Satisfactory 65

Unacceptable38

Your work-term-report mark is reported on your transcript, as an incentive for you to write the best

report that you can. The mark is not included in your term average.

Third and fourth year work reports are marked by one marker only who assigns a final grade from th

above table.

There are awards for top work-term reports: an award is given in each class to the writer of the best

SE non confidential work-term report submitted that term. Only reports that receive an evaluation of

Outstanding are eligible.

clearing failed reportsAn unsubmitted work report gets a mark of 38. For reports failed F09 or later, add the course

(WKRPT x00) on Quest for the term in which you wish to resubmit it. For reports failed prior to F09,

just submit the report in a subsequent semester and indicate that it is a supplemental report for

WKRPT x00. Under the new rules the mark for the resubmit will show on your transcript. Under the ol

rules you only get a "Supp Satisfied" beside the original 38

wkrpt coordinatorThe SE work report coordinator is usually a prof from ECE whose research area is in software


14/14


engineering. The current coordinator is listed on the academic administrators page. They may be

contacted by emailing [email protected].

7. references[1] Department of Electrical and Computer Engineering, "E&CE Work Term Report Guidelines",

University of Waterloo, Waterloo, Ontario, March 2005;

http://www.ece.uwaterloo.ca/~wtrc/WrkTrmRpt.html .

[2] Faculty of Mathematics, "Mathematics Work Report Guidelines", University of Waterloo, Waterloo

Ontario, March 2005; http://www.math.uwaterloo.ca/navigation/Current/workreport/index.shtml

[3] G.C. Andrews, J. D. Aplevich, R.A. Fraser, and H.C. Ratz, Introduction to Profession Engineering

in Canada, Prentice Hall, 2003, pg. 60.

[4] IEEE Computer Society, "IEEE Computer Society Style Guide - References", March 2005;

http://www.computer.org/portal/web/publications/style_refs .

Copyright 2007 University of Waterloo. All rights reserved.

software engineering _ current students _ policies and guidelines _ work report guidelines

Documents