Questions about the Design Report

Question:  I was just looking through the guidelines on the format of the report that we have to hand in on the Lego robot project. The work report guidelines on the SE page  (http://www.softeng.uwaterloo.ca/Current/work_report_guidelines.htm)  state that "Text shall be written in the third person, ...". Since Dupré says that we should use "you" and "we" while writing in order to engage the reader, I wanted to check whether we are supposed to be writing in the third person or if we are allowed to follow Dupré's guidelines.

Answer:  Good question!  You should follow the SE work-report guidelines and write in the third person, active or passive voice.  Dupré's guidelines are aimed at documents where the author is addressing the reader.  Technical documentation, like a work-term report, are not communiqués between the author and reader, but rather repositories of information about a project, and it is better to focus on the project rather than on the engineers working on the project.  In fact, Dupré does acknowledge that there is "one justifiable use of passive voice. Passive voice emphasizes the receiver of activity (the object), rather than the actor (the subject)" (pg. 4) -- which is exactly the emphasis we want to see in your report.


Question:   The "Work-Report Guidelines" (http://www.softeng.uwaterloo.ca/Current/work_report_guidelines.htm) say that "The report may be written either as an engineering analysis or as a synthesis." I'm not quite sure which one is applicable in this particular case.

Answer:  It depends on which tasks your subteam is working on.  In general, a design report documents and justifies decisions, usually design decisions.  It should read like a series of arguments:  it should describe problems, your solutions, and both the rationales and limitations of your solutions.

A synthesis report has the following structure:
    problem= some need to be met; some problem that needs to be solved
    solution=product
    justification=that the product satisfies the need, or solves the problem, or
        is the best possible solution

An analysis report has the following structure:
    problem=decide between alternatives (e.g., different ways to turn robot)
    solution=choice made
    justification=comparison (preferably quantitative comparison, or quantification
        of qualitative comparison) of alternatives, with respect to the particular problem
        at hand, and the particular usage.

We're not looking for a comprehensive report of every you did in getting your project to work.  We're not looking for quantity of accomplishments.  What we're looking for is your ability to recognize and document design decisions.