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.