Software Engineering - Current Students - Policies and Guidelines - Work Report Guidelines

4/16/12
software engineering > current students > policies and guidelines > work report guidelines
Copyright 2001 University of Waterloo. All rights reserved. software engineering > current students > policies and guidelines >
work report guidelines

introduction report topics confidential self-study reports report format evaluation: technical communication evaluation: technical content sophistication of the analysis or synthesis final mark clearing failed reports references wkrpt coordinator sample reports: example 1, example 2
1. introduction
We 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 starts 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 is 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 format. Technical-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 a 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 Engineering work-term reports.
www.softeng.uwaterloo.ca/Current/work_report_guidelines.htm
1/14
4/16/12
Engineering work-term reports.
The rest of this document is organized as follows. Section 2 discusses appropriate report topics, with an emphasis on the contents of, and the differences between, analysis and synthesis reports. Section 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 topic
A 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 softwarerelated 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, whether 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 general 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 students 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 software 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 project 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 are properties that discriminate better solutions from worse solutions (e.g., maintainability of the software, 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 specific 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 softwareengineering problem, or of a software-engineering decision to be made. It includes the following information:
www.softeng.uwaterloo.ca/Current/work_report_guidelines.htm 2/14
4/16/12
1. Problem: A choice to be made among alternatives (e.g., a choice between using C or Java on
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 project team, the environment in which the final product will be placed) and the design constraints and 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 a comparison preferably a quantitative comparison alternatives with respect to the specific of 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 why the 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 and 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 softwareengineering 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 coordinator may allow the www.softeng.uwaterloo.ca/Current/work_report_guidelines.htm report to be marked by the employer. In these cases the marker should be
3/14
4/16/12
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 it 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 letter of 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 format
IIn general, there is no single standardized format for software-related technical reports. However, many businesses establish company-wide standards for structuring documents. Such standards help 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 formatting standards that Software Engineering students follow when writing work-term reports. The checklist is not 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 of 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: Covers The 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, name 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

4/16/12
Verisoft, Inc. Waterloo, ON N2L 3T8
Prepared by Sally Niu Student ID: 12345678 Userid: sniu@uwaterloo.ca 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 it 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 what 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

4/16/12
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 of 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 of Submittal ), 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
Page 6/14
4/16/12
Page Executive Summary.................................................................................................................iii Table of Contents.....................................................................................................................iv List of Figures..........................................................................................................................v List of Tables...........................................................................................................................vi 1. Introduction..........................................................................................................................1 2. Automated Verification..........................................................................................................2 3. Data Structures for Modelling State Machines.........................................................................4 4. Performance Analysis...........................................................................................................8 4.1 Space Complexity........................................................................................................8 4.2 Time Complexity........................................................................................................11 5. Conclusions.......................................................................................................................14 6. Recommendations..............................................................................................................15 Acknowledgements.................................................................................................................16 References.............................................................................................................................16 Glossary................................................................................................................................17 Appendix A - Detailed Space Complexity Analysis.....................................................................18 Appendix B - Detailed Time Complexity Analysis.......................................................................21
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 the 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 pages long. 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 either
4/16/12
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 decreasingsized fonts (e.g., 16-pt section headings, 14-pt subsection headings, 12-pt sub subsection headings). 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 of the appendix label and figure/table number within the appendix (e.g., A-1, A-2). Each figure and table is cited (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 communication
Technical communication pertains to the effective communication of technical information. The technical-communication www.softeng.uwaterloo.ca/Current/work_report_guidelines.htm marker evaluates the quality of communication in a report, with respect to
8/14
4/16/12
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 that figures and tables are self contained, and use captions (figures), legends (tables or graphs), and axis annotations (tables or graphs) to convey explanatory information. Relegate complex details 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 use 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 are 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 in 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 and 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 as unacceptable.
5. technical content
The 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 are followed by a subsection that discusses how standards for evaluating technical content correspond to 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 company executive officer) www.softeng.uwaterloo.ca/Current/work_report_guidelines.htm who is not likely to read the report itself.
9/14
4/16/12
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 the 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 of 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 Main Sections start by elaborating on the problem identified in the Introduction, expanding on the problem definition 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 satisfies 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 be 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 differentiate among 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 report, yet whose contributions were not so significant as to warrant the helper(s) being named as coauthors. This includes anyone who was interviewed, anyone who proofread the report, or anyone whose files were used in the writing of the report.
10/14
4/16/12
whose files were used in the writing of the report.
Glossary Avoid using highly technical terms and acronyms, so that your report is easily read and understood by 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 of interest 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 two 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 seniorlevel 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 Y 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 sufficient detail 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 of n3, 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 conclude 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, as 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 be 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
1) What the potential values of n are. If the algorithm is being used by a customer application, then
11/14
4/16/12
1) What the potential values of n are. If the algorithm is being used by a customer application, then 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 lend themselves 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 see 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 softwareengineering 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 a 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.
12/14
4/16/12
6. final mark
First 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 matches the technical-content score. Technical Technical Content Communication 0 1 2 3 4 ... 0-5 6-8 9-11 12 Unacceptable Unacceptable Unacceptable Unacceptable Unacceptable Resubmit Satisfactory Satisfactory Unacceptable Satisfactory Satisfactory Very Good Unacceptable Satisfactory Very Good Excellent Unacceptable 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 is evaluated 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 Unacceptable 38 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 the 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 reports

An 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 old rules you only get a "Supp Satisfied" beside the original 38
wkrpt coordinator
The SE work report coordinator is usually a prof from ECE whose research area is in software
4/16/12
engineering. The current coordinator is listed on the academic administrators page. They may be contacted by emailing sewtrc@ecemail.uwaterloo.ca.
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.
14/14

Software Engineering - Current Students - Policies and Guidelines - Work Report Guidelines

Hochgeladen von

Dokumentinformationen

Originalbeschreibung:

Originaltitel

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Software Engineering - Current Students - Policies and Guidelines - Work Report Guidelines

Hochgeladen von

Copyright:

Verfügbare Formate

4/16/12

work report guidelines

Engineering work-term reports.

UNIVERSITY OF WATERLOO Software Engineering

Data Structures for Modelling and Analyzing State-Machine Executions

Verisoft, Inc. Waterloo, ON N2L 3T8

home_address September 13, 2005

whose files were used in the writing of the report.

clearing failed reports

Copyright 2007 University of Waterloo. All rights reserved.

Das könnte Ihnen auch gefallen