What is a Report?
                               Gunnar Gotshalks
                                 1997 January


A report is a description, either oral or written, of something seen
or done.  Oral reports tend to be informal in style, structure and
language while written reports tend to be formal in style, structure
and language.  In a report you are trying to tell the reader all or
some of the following things; depending upon the objectives of the
report.

  -- The context, or circumstances, in which you did something.
  -- What you did.
  -- Why you did it.
  -- Give supporting evidence that what you did was reasonable
     and correct.
  -- How you did it.
  -- How others can make use of what you did.

A professional report is done in a workman like manner.  It is well
organized and well structured.  It is neither too long (padded) nor
too short (misses essential points).  It addresses the proper points
and does not digress off the point.  The report looks good but is not
flashy -- no need for fancy desktop publishing.

Writing a report is very similar to writing a program.  The former is
in English, the latter in a formal programming language but both
require carefully designed logical and physical structures.

There is no single way of organizing a report but there are general
guidelines in that you have an introduction, body and conclusion for
the work as a whole, for each section, subsection, etc.  At the lower
levels the introduction and conclusion become briefer with more
emphasis on the body.  Often a top down structure is used with lower
level sections being more detailed descriptions of more general upper
level secitons.  Logically related sections are physically close.

You have to make decisions based on what you are trying to describe in
your report.  What is important needs to be emphasized and described
at greater length.  What is unimportant is described briefly, if at
all.

You have examples all around you.  Examine the structure and contents
of your technical text books.  Examine the structure and contents of
the *.ps files in /cs/course/1030/notes/*.  Examine articles in
technical journals in the library.  Examine the guidelines for your
1020 reports.  They all partition a larger work into sections and
subsections, etc.

In courses you are asked to do assignments -- the instructor assigns a
task for you to do.  You do not submit an assignment in response to the
task -- you are not asking the instructor to do the task -- you submit
a report of what you did in doing the task you were assigned.

Reports must be customized to the task.  You have to think about what
is important to describe and what is unimportant.  A report describing
the design of a program will have different sections and different
emphasis than the following: a report describing how you proved a
program correct; or how you tested a program; or a comparison of
similar but different data structures.  For a design you describe the
problem (specifications) what data structures you selected, how you
refined the problem into abstract data types, procedures and
functions, modules, files.  For testing you describe tests plans, how
you generated the test data, what you observed, what conclusions you
drew, how an initial test plan led to a more refined test plan.  For
data structure comparison you describe the properties of each data
structure, how they are similar, how they differ, give an opinion as to
which is better under what circumstances.

For assignments it makes sense to structure your report based on the
tasks you have been assigned on which you will report what you have
done.  If given multiple tasks then, generally your report would have
specific sections for each task and the sections would appear in the
order they were assigned.  The first part consists the body of the
report, the second part consists of the supporting documents such as
program listings, test input files, demonstration output scripts, etc.