Suggestions for Project Reports in MCS 170
A very short sample project report is available entitled Hello Me Web Page
General advice
After you have finished carrying out the task outlined in the project
assignment, you need to write a report that outlines the project task,
describes your work on this task, and shows testing of your work to
ensure correctness of solution. The project report is similar to papers
that you write for other classes in that
it should have an introduction, a body and a conclusion.
The introduction explains to your readers what the report is about
and
why they should read it. It gives a road
map explaining the report's structure. The body of the report describes
your work in detail, along with any code, analysis, or research that
you have
done for the project. Although most of the assignments present a list
of questions and/or tasks
that are meant to guide you through the project, you should not use
these questions to organize your report. Instead, you should organize
it so that you present the material in a logical and coherent manner.
Finally, the conclusion should summarize what was learned during the
project.
Assume the audience includes people who have taken a similar course
somewhere else. This means that they haven't read the book or the
project assignment, but that they do know basic HTML and JavaScript. If
necessary, you
may assume the reader has a copy of the book handy so that you can
cite it.
Using code in your reports
You will write, test and debug JavaScript code for many of the
projects, and you will
often need to put this code in your paper. You want to do this in
such a way that your reader can easily understand what the code does
and
how it works. You also need to convince the reader that the code
does work, usually by presenting (i.e., describing and giving examples
of) your testing.
- Present your code in an understandable way. Remember, the
audience you
are writing for has read neither the book nor the lab description, so
your
code should either be self-documenting or have enough documentation so
that it's clear what it does.
- Describe how you tested your code. You don't always need to
provide
the individual test cases, but you should convince the reader that you
have
tested every procedure. If a procedure does not always work,
you should report this,
too.
- Use
a
fixed-width character font like courier or typewriter
font for your code so that the code will be easily distinguishable from
the rest of your report.
Project report DOs and DON'Ts
- Do use complete sentences, with proper grammar and spelling.
- Don't blindly write up your project in the same order and format
as the assignment.
- Do structure your paper in a logical way, with each section
marked
with a helpful title. (``Part 3'' is not helpful. ``Data'' or ``Part
3: Data'' or ``3.1 Data'' is helpful.)
- Don't repeat the programming questions. Don't write ``Question
1''
or ``Exercise 3.1''.
- Do focus on what the reader should learn rather than what you
learned or did:
- Don't use phrases like, ``In this lab we learned about...,''
nor,
``We were asked to write a procedure which, ...''
- Do use phrases like, ``The following procedure computes ...''
- Don't use the passive voice, ``A procedure was written to ...''
- Don't mix verb tenses. Usually, I would recommend sticking to
present tense.
- Do attach a copy of the college's Honor Pledge to your report and
sign it. (A copy of the pledge can be found on the course web
site)