TEACH REPORTS                                      Aaron Sloman Dec 1989
                                                     Updated 4 Dec 2000

                     ON WRITING REPORTS ON PROGRAMS
                     ==============================

CONTENTS

 -- Background and revision
 -- Why reports are as important as programs
 -- The format for reports
 -- 1. "FRONT MATTER" (Your name, etc. etc.)
 -- 2. INTRODUCTION (Including motivation).
 -- -- Introduction: Motivation
 -- -- Introduction: The problem domain
 -- -- Introduction: Summary of achievements and unachieved targets
 -- 3. ILLUSTRATION (Scenario)
 -- 4. EXPLANATION (The high level design)
 -- -- WHAT is the problem and HOW is it solved?
 -- -- Ontology and data structures
 -- -- The architecture of the program
 -- -- Special difficulties
 -- -- Interesting algorithms
 -- 5. INSTRUCTIONS FOR USE OF YOUR PROGRAM
 -- -- NB. Get another student to check your instructions
 -- -- Note on file names.
 -- 6. RELATED WORK
 -- 7. LIMITATIONS
 -- 8. CONCLUSION
 -- 9. BIBLIOGRAPHY
 -- 10. ACKNOWLEDGEMENTS
 -- 11. Appendix 1 (The program listing)
 -- -- Format of program files
 -- -- Make comments informative
 -- -- Style is important
 -- -- Using code from teach and program library files
 -- -- Functionality
 -- -- Collaborative projects
 -- 12. Appendix 2 (Additional trace output, or Examples)
 -- 13. Other Appendices
 -- Length of report
 -- Style
 -- Who are you writing for?
 -- Explaining how a procedure works
 -- Formatting and printing your report
 -- -- ENTER psprint -p -ns (for program files)
 -- -- Long lines in the program
 -- -- Formatting with Latex
 -- -- Line spacing: DO NOT USE DOUBLE SPACING
 -- How to get computer printout into your report
 -- Physical presentation
 -- (1) Packaging
 -- (2) Margins
 -- (3) Use appropriate font size
 -- (4) Front page
 -- (5) Cover sheet
 -- Spelling, grammar, etc.
 -- On planning a project
 -- Plagiarism, collusion
 -- And finally

-- Background and revision --------------------------------------------

This teach file gives suggestions for writing reports on term time
programming assignments, especially in the first year, or at the end of
your first programming course.

For advice on how to write up longer more ambitious projects see
    TEACH PSTYLE and TEACH PGUIDE
(Both written a long time ago. Possibly partly out of date)

Your work on the project and the report will be facilitated if you are
really fluent in the use of VED. For revision see:

  TEACH TEACH, VED, BUFFERS, MARK, LMR, VEDPOP, VEDNOTES

For revision of Pop-11 you can look at the core sections of the
POP-11 Primer (Preface and Chapters 1 to 7.)
TEACH TRACE shows how to turn tracing of individual procedures on and
off.
A summary of the main features of the language is in TEACH POPCORE.
For general revision exercises see TEACH REVISE. You can find some
answers in TEACH REVISE.ANS

Files specifically concerned with the end of course mini-project are:

  TEACH PROPOSALS
    This tells you how to plan for a programming project.

  TEACH TRAIN_CLERK,
    Gives an example of how to do this, using as illustration
    the task of designing a simple project in an introductory course.

  TEACH POP11_PROJECT
    This gives high level objectives for a project or mini-project and
    some examples of possible project topics.

  TEACH AI1PROJECT.CHECKLIST
  TEACH MSC.PROJECT.CHECKLIST
    These two files give sample "checklists" to be used by the person
    marking a mini-project. By looking at them early on and also when
    you are close to finishing your project you'll get an idea of the
    points a marker is likely to be looking for when reading your
    project.


The rest of THIS file concentrates on how the project should be written
up. You should read it once while planning your project and then
read it again more carefully before you start writing your report.
Then read it again before you print the final version of the report.

-- Why reports are as important as programs ---------------------------

Being able to write programs that work is important, but even more
important is the ability to think and write clearly about what the
program is for, how it works, and how it is to be used, what its
strengths and weaknesses are, and how it relates to other programs
purporting to do similar things. It is therefore important to have
practice at presenting reports on your programs, no matter how simple
the programs are.

One reason for writing a report is that your attempts to explain things
may help you (and possibly your tutor) to discover points that you have
not understood fully.

That provides an opportunity to remedy the misunderstanding. It also
provides an opportunity find out if you need help improving your
expository skills. In a well-funded university system we would ask you
to write frequent reports as part of the teaching process. But our
government no longer believes in "individual" feedback at university
level.

Before starting work on a project you should read TEACH PROPOSALS. That
will give you a framework within which to think about your objectives
and how to achieve them. If you write notes corresponding to the format
it recommends that will help you prepare for your final report.

The main point of your report is to give the reader a clear view of what
you were aiming to do, why you were trying to do it, what you managed to
achieve, how you achieved it, what its limitations are, how you might
improve it if you had more time, and how it relates to other things you
have read about. No matter how good the program is, you cannot get a
good mark for the project unless the report is also good. Of course,
the program must also be good for a really good mark.

-- The format for reports ---------------------------------------------

The report should start with the following items.

-- 1. "FRONT MATTER" (Your name, etc. etc.)

The report should start with the following.

A. Your full name

B. The degree for which you are studying.

C. The course for which this is an assessment exercise: give the course
code and the course title.

D. The submission date.

E. The approximate number of words in the report, excluding front
matter, bibliography and appendices.

F. The title of your project (NOT title of the course).

The title should not be something uninformative like "Programming
project". It should be something like "The world's best chess program",
or "Automated surgeon", etc. This title should be on the first page of
the report and also on the cover sheet provided by the School to be
attached to reports.

G. A short abstract (e.g. 5 to 10 lines), with the heading "ABSTRACT".

H. If it is a collaborative project, add a section labelled "In
collaboration with" ... and list the collaborators.
Each collaborator must submit a separate report. Each report should be
written separately, and each must include a section saying who did what.

I. A table of contents, listing main sections, including bibliography,
and each appendix listed separately, ALL with page numbers.

The rest of the report should normally include the following sections
though not necessarily in this order. Discuss the plan for your report
with your tutor or a demonstrator.

-- 2. INTRODUCTION (Including motivation).

-- -- Introduction: Motivation
The introductory section, or a section coming soon after the
introductory section should provide a general description and
motivation for the program. Include:

    A brief explanation of what the program does and why anyone would
    want to write or to use such a program. Even if this has been stated
    in a TEACH FILE or a handout from a tutor you should state it in
    your own words. (to show your own expository skills.)

-- -- Introduction: The problem domain
After a brief introductory overview you should give as precise as
possible a characterisation of the problem domain, and what your program
does in that domain. Don't assume your reader knows about the domain.
E.g. if it is a game playing program describe the game. If the rules are
complicated put them in an appendix, and refer to the appendix in the
introduction. DO NOT ASSUME the reader will know the rules of the game.
If the rules are too complex to include in your report, it is very
likely that the game is too complex for a project.

TEACH PROPOSALS explains how you should produce an ontology and
behavioural specification when planning your project. If these are
short (e.g. no more than a page), include them as part of the
introduction to the report, in a subsection. If they are too long,
include them in an appendix, and summarise them in the introduction.
The introduction should mention this appendix, if it exists.

-- -- Introduction: Summary of achievements and unachieved targets
The introductory section should make clear not just what the domain is
and what your intentions were, but what has ACTUALLY been achieved, i.e.
what the program already does.

If necessary indicate clearly what the program does NOT do. I.e. make
sure the reader has no excessive expectations. If you did not manage to
get the program working in the time available, be honest and say so.
You can include examples of parts of the program working in the
appendices or other sections.


-- 3. ILLUSTRATION (Scenario)

This section should include a few typical illustrations of the program
working, with brief explanations, to help the reader know what you have
achieved and what it is like to interact with your program. This could
be very similar to a scenario in your proposal.
(See TEACH PROPOSALS. An example scenario is in TEACH TRAIN_CLERK)

Putting the scenario near the beginning of the report will help give the
reader a good context for understanding your explanations in later
sections. Make sure the illustration is readable and interesting, and
not just several pages of indigestible computer printout.

    This could include TRACE printing, showing the activations of
    your procedures (See TEACH TRACE) - but not too much to digest.

    Use limited, interesting bits of trace printing, not masses of
    boring or unintelligible printout.
    DO NOT INCLUDE SEVERAL PAGES OF UNEDITED TRACE PRINTING.
    Nobody can read that.

    Always ask yourself "Would I like to read that?"

    It is sometimes also useful to trace system procedures like MATCHES,
    READLINE, ADD and REMOVE, but they will generally produce far too
    much printing, and nobody will want to read it.

    The sample output should simply be used to highlight interesting
    points about the program. If necessary add special printing
    instructions to your program to make it produce an informative
    record of what it is doing. (See HELP PR,  HELP PRINTF)

    You can produce sample printout in your 'output.p' file by using LMR
    as explained below, and then copy it into your report file using
    ENTER ti (or mi) as explained in TEACH MARK. (To remind yourself
    of facilities in the editor it may be a good idea at this stage to
    review TEACH VEDNOTES)

If your program uses graphics you may not easily be able to include
samples of graphical interaction. However there are techniques for
saving a graphical window in a postscript file which can then be
printed, and stuck in your report, or possibly included in the report
file if you use Latex to produce the report. (See below.)

-- 4. EXPLANATION (The high level design)

This section should give an explanation of how the program works.

This should NOT describe every line of the program, and not even every
procedure, but should give an overview of what sorts of things
are represented, how they are represented, where input comes from, how
it is transformed, where output goes to, etc. The explanation should
refer to a copy of the program attached as an appendix to the report.
Diagrams showing the architecture may be useful. (See below)

-- -- WHAT is the problem and HOW is it solved?
Explain WHAT problems your program had to solve, but don't describe the
problem in terms of internal operations in Pop-11. E.g. describe it as
trying to win a game of noughts and crosses, or trying to manage a
user's diary of appointments, not as trying to do something with its
internal database.

Explain the high level strategy for solving the problem. Do this in a
manner which is independent of Pop-11, and should make sense to a user
of another programming language. Don't mention particular procedure
names or variable names. Those are mere "implementation details", and
will not interest the general reader.

-- -- Ontology and data structures
Make sure you describe what kinds of objects are represented (i.e.
mention the ontology summarised in the introduction or in an appendix),

Explain how the objects, properties, relations and events are
represented in the computer. (e.g. using lists, or vectors, or numerical
values for variables or whatever). I.e. present the ontology of the
problem domain as well as the structures in the computer: the "external
semantics" of the program and the "internal semantics". Don't confuse
the two. (See chapter 2 of the Pop-11 Primer.)

Use tables or diagrams if necessary to make the ontology clear.

-- -- The architecture of the program
Often a program has an architecture which can be described with the help
of a diagram. The architecture outlined in TEACH RIVERCHAT had three
main components with two-way interactions, as follows

    Interface   <-----> Response  <-----> World model
    controller          generator         manipulator

This might be broken down further. For instance the world model
manipulator might have separate sub-components, one to answer questions,
one to store new information provided by the user, and one to perform
actions changing the model. The response generator might have two
components, one to transform the sentence typed in into a form suitable
to hand to the model manipulator, and one to transform results from the
model manipulator into sentences to be printed out. There may be another
component which checks the validity of what the user types in and if it
is in an inappropriate format asks the user to re-type, perhaps giving
some advice or help as to how to do that.

Similarly problem-solving and searching programs, like those described
in TEACH TOWER and TEACH SEARCHING, which explore a search space may
have an architecture in which you can separately describe a component
which recognises goal states, a component which generates new states
from old ones, a component which decides which unexplored state to
examine next, and so on. (See chapters on searching in books on AI, and
the general problem solver in chapter 8 of the Pop-11 primer.)

How to break down your program into separate components is an art which
you will learn from experience. In your report label the different
components of the architecture in a manner which suggests their
function, and if possible show their relationships in a diagram,
e.g. depicting how information flows between components.

Also state clearly which appendix includes the code for each of the main
components of your architecture, including page numbers to make it easy
for the reader to find a procedure definition.

-- -- Special difficulties

If you had any special difficulties in your implementation you can
describe them and how you overcame them (if you had help, say so).
If you failed to overcome them, say so.

-- -- Interesting algorithms

Sometimes overcoming a difficulty involves inventing (or copying from a
book or teach file) a specially interesting algorithm or procedure. If
you have any such algorithms summarise them in this section of the
report. Don't simply reproduce the Pop-11 code. Instead give a "high
level" description using English or pseudo-code, perhaps with numbered
steps. If necessary use a flow chart or some other diagram. But also
state clearly which sections of the appendices contain these algorithms
so that the reader can look them up.


-- 5. INSTRUCTIONS FOR USE OF YOUR PROGRAM

Make sure that your program can be tested by someone other than
yourself. The report should contain a section giving instructions
on how to run the program. (This could be in an appendix rather than the
main report). The instructions should state which directory the program
is in.

E.g. if your user name is ug68xyz and your program for designing teapots
is in your subdirectory called 'project1' then your section on how to
run the program can say:

A. The program is in the file

    ~ug68xyz/project1/teapot.p

    (Notice the use of "~" before your user name.)

B. The program can be run by compiling that file and then giving the
following command (or whatever is needed):
    tea_party([bob sue mary william]);

If the program can be run in different ways describe them.

Note 1. If the user has to type in sentences or commands of some kind
make sure that EITHER the program gives clear instructions on which user
inputs are permitted, OR make your report explain this clearly, or do
both!

Note 2. If you create a file giving instructions, your report should
give the full file name so that the reader can go and look at it. It is
common to put instructions in a file called 'Readme' in the same
directory as the program file, but you can use another name if you
prefer, e.g. 'Instructions'. E.g. add something like this:

C. Full instructions for running the program can be found in the file:
    ~ug68xyz/project1/Instructions

(Do NOT use .p at the end of the name of a text file. '.p' is for
Pop-11 program files.)

The instructions file should contain at least one example of a command
to start the program and some examples of things you can type in or do.

-- -- NB. Get another student to check your instructions

In your report, explain clearly what the user has to do in order to run
your program. Get another student to check that your filenames and
instructions work. Something that works for may not work if someone not
logged in as you tries to run your program. (E.g. you may have
accidentally protected your directory. Or you may have forgotten
to use full file names in "load" commands. See HELP COMPILEHERE

DO NOT TRY TO TEACH THE USER HOW TO USE VED, ENTER LMR, ETC.
Assume that the user already knows how to use the editor and how to
get a Pop-11 command obeyed, and how to compile a file, e.g. using
load, or compile or ENTER l1.

So all you need to specify is which files to compile, and which
procedure to run with which arguments.

-- -- Note on file names.

Pop-11 program files should have names ending in '.p' to help the editor
and the compiler deal with them properly.

Names of text files giving instructions or other information should not
end in '.p', otherwise you may have trouble formatting them. Thus you
could have an information file called 'Readme', or 'teapot.txt'
describing the program in the file 'teapot.p'

A common suffix for a plain text file is '.txt'


-- 6. RELATED WORK
Your report should include a section on related work.

If you have read about any work done by anyone else that is relevant
to your project you should include a comparison. E.g. you might say
that you used ideas from such and such a book, or teach file. Or you
might say that so and so's program had certain flaws and your
program attempts to overcome them. (See the section on bibliography
below.) A report that shows no knowledge of any of the AI literature
will not do as well as one that does. Search AI textbooks (listed
previously) and relevant journals, e.g.

    Artificial Intelligence
    Computational Intelligence
    Cognitive Science
    Artificial Intelligence Review
    The AI Magazine
    Intelligence (SIGART magazine)

Some of these are in the school library. You may find several others.


-- 7. LIMITATIONS

This section should discuss the limitations of your program and possible
future developments.

Don't be afraid to criticise your own program. If you have read about
similar programs, or related programs that go further than yours do, it
may be appropriate to include some comparisons. For instance you could
compare your program with a program described in a teach file, or one of
the text books you have used.

If you have any ideas about how the program could be extended, say what
the extension would achieve and how it might be implemented. Your report
will be marked in part according to how well you can critically evaluate
your own work.

-- 8. CONCLUSION

Briefly summarise what has and has not been achieved.

What lessons, if any, have been learnt about the problem, or about your
original approach to the problem? What, if anything, has been explained
by your program (e.g. does it explain how people perform some task?)?

Were your goals achieved? Is there anything you now think you should
have done differently? How does what you have done compare with items in
the literature?

In this section you don't need to say what you personally have learnt
about programming, or how you have enjoyed or hated the project etc. If
you have comments like that you can put them in an acknowledgements
section or an appendix.

Note: a software engineering course might require you to include a
"project diary" in your report, including all the main decisions you
took, when you took them etc. This is NOT required for an AI
mini-project report. This report is about the results not the process.

You can include comments on things you would have done differently with
hindsight, however.

-- 9. BIBLIOGRAPHY

List books, articles and TEACH or HELP files considered to be
relevant.

For the format of the bibliography look at bibliographies in books or
articles, or book lists provided by your tutors.

List all the relevant literature in the standard format for essays. Give
first name or initials plus surname for all authors.

If you cite a book give author(s) title, publisher and date.

If you cite an article give author(s), title of article, title of
journal or book containing the article and additional information.

E.g. if it is an article in a book give the names of the editors of the
book, the publisher and the year of publication. If it is a journal
include Volume and issue number, and year of publication. For articles
in books or journals also give the page numbers. For teach files it
suffices to list the names of the files. Include only directly relevant
teach files.

NB: if you quote a sentence or paragraph from some book or article,
the quotation should specify not only the source, but the page
number.

-- 10. ACKNOWLEDGEMENTS

If people have helped you it is conventional to include some
thanks. More specifically if your program includes bits of code from
libraries or programs produced by other people then you should make
that fact very clear in your acknowledgements section, and also
by using comments in the program itself.

If you worked on a collaborative project you should state who else
worked on the project, how it was managed, and who did which portions of
the work. But it is important that you write your own report.


-- 11. Appendix 1 (The program listing)
NB: The appendices should have page numbers and the table of contents
at the beginning of the report should give the page numbers. You can
add them by hand after printing.

The report can include one or more appendices. Each appendix should be
listed in the table of contents (with its page number), and referred to
where appropriate in the main text of the report.

One appendix should include the whole program, with comments explaining
what the procedures do, what the global variables (if any) are for, etc.
If your program is too long for a single appendix, e.g. if it is made up
of several different files, then you can use several appendices, one for
each file. Change numbering of the following appendices, accordingly.
Make sure your table of contents lists the separate files


-- -- Format of program files

Each program file should have a separate header: use ENTER fileheader in
VED to produce a header for a program file, which you can then edit.

Each non-trivial procedure should have a comment explaining what it
does. Use ENTER procheader to produce a header template for a procedure.
See HELP VED_PROCHEADER for the various formats and advice.

-- -- Make comments informative

If you have an input or output variable don't simply say that its value
is a list, or word or number, say also what the list, or word or number
represents. (I.e. give the "external" semantics, as well as "internal"
semantics, in your comments.)

Assume the reader of your program already understands Pop-11. Do not
insert comments which state what is totally obvious to such a reader,
e.g. ";;; declaring a variable", or "assigning to the variable input".
That sort of thing is much too low level.

Comments should explain the UNobvious significance of the instructions
in the code: don't just translate the pop-11 directly into English in
your comments. Give a higher level overview of what's going on, to help
the reader (and you) understand your program.

-- -- Style is important

In part your program will be assessed for style as well as what it does.

Don't use global variables to communicate information between
procedures: use arguments and results for that. (TEACH STACK)
If you do need global variables, e.g. to represent some global state,
make sure you declare them at the TOP of your program, and include
comments saying what they are for, and what initial values they get.
Also choose good names for them, e.g. "route_data", not "rd". Names of
local variables (lvars) should also be clear and helpful.

Try to use procedure names that indicate what they are for. I.e. not p1,
p2, p3, but something more meaningful: find_lines, find_squares,
describe_picture, etc.

Make sure your procedures are properly indented to show their
structure. E.g. use the ENTER jcp command. See HELP MARK
But see comments below on ensuring that your program PRINTS
in a readable format.

Do not use long procedures. Wherever a procedure looks like taking more
than about 10 lines consider whether it should be broken into smaller
procedures each with a clear name to say what it does. Certainly do not
write procedures which are so long that they take over a page to print
out. Usually that is a sign that you have not thought clearly about how
to break down your program into components. (There are some exceptions.
If in doubt ask your tutor or a demonstrator.)

-- -- Using code from teach and program library files
If you have written a report based on extending a library program you
must indicate very clearly which bits are yours. You can either do this
for each procedure, or else copy the parts of the program that you
developed into a separate file and attach that as well as the complete
program.

-- -- Functionality
The assessment of the program will be based not only on whether it
achieved what you set out to do, but the difficulty of doing that and
whether it made adequate use of the sorts of techniques that were taught
in the course. A program that repeatedly uses only a single simple
construct, e.g. simple condition action rules in poprulebase, or an
eliza-like if-then-elseif-then-elseif-then.... format will not get a
high mark even if you put lots and lots of information into it, e.g.
regarding how to choose a plant for your garden. If in doubt as to
whether your proposed program has adequate functionality, ask your
tutor.

-- -- Collaborative projects
If parts of the program were written by other students list the authors
of the procedures very clearly. E.g if the work of different students is
divided into different files, then the file headers can specify the
author (and collaborators). If individual procedures were written by
different students, then indicate the authors in the procedure headers.

-- 12. Appendix 2 (Additional trace output, or Examples)
The main report should include some examples of the program working.
If necessary you can extend the illustrations in the text with an
appendix giving more detailed examples of the program running, with
printout showing clearly what the program does.

Do this only if your main text does not already do this adequately.

NB. Do NOT produce several pages of indigestible trace printing. Make
sure that what you produce is readable. If necessary, highlight portions
with a pen, or edit in explanations in English of what is going on
before you print the trace output.

Also make sure that the trace printout does not go on and on repeating
the same sort of thing. Edit out repetitive bits. Edit in comments. Mark
the most interesting bits of the printout in ink to draw attention to
them, and in the text explain what is going on.

Above all, always think of the poor reader, who needs to be motivated,
informed and entertained.

DO NOT hand in several un-annotated pages of trace printing that nobody
will want to read.

-- 13. Other Appendices -----------------------------------------------
You may find it useful to include additional appendices, e.g. giving the
rules for the game your program plays, or the data on which your program
operated, or some information about how you tested your program, or a
detailed description of a particularly complex part of your program, or
possibly diagrams showing some of the structure.

-- Length of report ---------------------------------------------------
The required length will vary from course to course, and will be
specified by your course tutor. As a default, assume that a first year
undergraduate mini-project report should be no more than about 2000
words, apart from the bibliography, acknowledgements and appendices.
A report for a double-weighted MSc course will have a larger upper limit
e.g. about 4000 words. Note these are UPPER limits, not required
lengths.

(NOTE: HELP WC tells you how to use a VED facility for counting the
words in the current file, or in the marked range.)


-- Style --------------------------------------------------------------

In the introductory motivation section make sure that you describe the
problem in a manner that is independent of how your program works. ("My
program looks after the bank accounts of property tycoons", NOT "My
program calls procedure xxx which calls procedure yyy which....").

In the "Explanation" section describe the nature of the solution, using
diagrams if necessary, again without describing details of the program
or the language used. Remember, anyone who wants to know the details
should be able to read your program if you have laid it out well, put in
good comments and chosen good names for variables and procedures.

So the explanation in the report should describe the "high level" design
features, e.g. what sorts of representations were used, what sorts of
inferences were required, what sorts of plans were created, what sorts
of searching was involved, what sorts of data-structures were used for
different things in the ontology, etc.

Explain the high level decomposition of the program into main parts
performing different tasks (e.g. managing a database, making inferences
or solving problems, interacting with the user, handling the graphics).

If appropriate use a diagram to show the structure of the program.

Try to give a global description of where input to the program comes
from (e.g. from the user, from a file, from an initial database provided
to the program) and how the output is produced, or how the program does
what it is supposed to do.

DO NOT translate your program line by line from POP-11 into English.
That will generally produce an incomprehensible or useless explanation.
If you give line by line explanations of all your procedures: the reader
will then not be able to see the overall structure.

Instead give a GENERAL account of what the program does, and how it does
it. But try to make it so clear that a reader with a lot of programming
experience could re-invent the same sort of program from your
description!

If you use poprulebase, do NOT translate the rules one at a time. The
reader can read the rules. Instead talk about the different groups of
rules and what sorts of different tasks they have. Explain how you
controlled the order of firing of rules, and any problems that had to be
overcome to do that.

If possible explain the advantage of using the design you chose, as
compared with alternative possible designs. Ignore this if you have not
investigated alternative designs.

In your explanations, always avoid the level of detail that can easily
be found by reading the code. Explain the overall STRATEGY used in your
program independently of whether the program is in POP-11 or any other
language. E.g. in your main overview description of how the program
works there is no need to mention particular variables and POP-11
procedures.

If you must describe a particularly important procedure, describe it in
a program independent way. E.g. you might say something like this:

    The procedure is used to find a value associated with a type of
    attribute. It takes a list of attribute value pairs, represented
    as words, and a word which is an attribute name. It returns the
    corresponding value if there is one, otherwise false.
    To find the value it searches down the list looking at the first,
    third, fifth item, etc. to see if it is the same as the required
    attribute. If so it returns the next item after the attribute found
    as the value corresponding to that attribute. For example, ....

Then give a simple example.
    E.g. if the program is given
        the list [colour red size six shape square]
        the word "size"
    it returns the word "six".

Notice how that explanation could apply equally to a program in any
language that can handle lists.

Use diagrams or tables when they will help you make the structure of
your program or ontology clear for the reader.


-- Who are you writing for? -------------------------------------------
Don't write as if you are communicating with your tutor who knows all
about it anyway. Equally don't write as if for an idiotic novice.

Try to write for an audience consisting of fellow students who may be a
week or two behind you in their understanding. Assume your reader can be
expected to understand about as much Pop-11 as you do. The reader should
NOT need a tutorial on the basics of Pop-11 or the editor.

You can assume the reader knows about procedure definitions, variables,
the matcher, conditional instructions, etc. If you are using
Poprulebase, assume the reader already understands what a rule based
system is. Don't bother to explain the syntax of the language.

The reader will not know what you were trying to achieve, nor what the
global strategy for achieving it was, so describe that. In particular
make sure you explain

    a. which items of information are represented in your program,
    b. how they are represented (e.g. using numbers, lists, lists of
        lists, etc.)
    c. how they are manipulated.

It may help to include a diagram in the form of a tree or network,
showing which procedures call which others, and then show, on the links
of the diagram what inputs go from caller to callee, and what outputs go
from callee to caller. If a procedure gets information from a stored
structure or puts information in a stored structure you  can indicate
this too, though make clear that your diagram does not confuse
structures (e.g. the database, or a turtle picture) with procedures
(e.g. add, present).


-- Explaining how a procedure works -----------------------------------
When explaining a particular procedure always start by stating what
sorts of inputs the procedure takes, and what sorts of outputs it
produces, preferably with one or two examples showing how it does so.

E.g.
    member(item, list) -> boolean
      - takes an item (of any type) and a list (of items of any type)
        and returns TRUE if the item is in the list, and otherwise
        returns FALSE:
            E.g.
            member("cat",[ant badger cat dog elephant]) =>
            ** <true>

            member("cat",[ant badger cow dog elephant]) =>
            ** <false>


If there are no inputs, or no outputs, then say so. E.g.

    start()
      - this procedure takes no inputs or outputs. It ....

If anything is printed out by the procedure say so, but don't confuse
printing things out with producing results. (Results are left on the
stack for another procedure to use, and need not be printed out, though
they can be. See TEACH STACK for details.)

Your main report should not include explanations of individual
procedures unless they are particularly important and complex procedures
that need to be explained.

-- Formatting and printing your report --------------------------------

The essay should not be hand written. If you don't have your own
word-processor, learn to use our machines to prepare a printed version.

-- -- ENTER psprint -p -ns (for program files)

You can simply use the "ENTER psprint" command to print out a report
written as a plain text file, like our teach files. If you do that, make
sure you use this command:   ENTER psprint -p -ns

The "-p" specifies that the file should be printed in "portrait" mode,
i.e. not printed out in "wide" mode (or "landscape" mode) with two
pages side by side.

The "-ns" means it should be printed with no surrounding borders (a
black rectangle surrounding the text).

You can also use that ENTER psprint command to get your program files
printed out, but it is desirable to use something better to format the
main part of your report.

If your program is very long (e.g. 20 pages or more), you can reduce the
amount of paper required to print it out if you leave out the "-p" bit
of the above command. The program will then print two pages per sheet.
Make sure that those pages are not clipped or bound into the main report
in such a way as to make them hard to read. (See discussion on physical
packaging, below.) Do NOT use side-by-side printing for the main report.

If you use the ENTER psprint command you will get a default font size
depending whether the "-p" is there or not (slightly bigger font for
portrait mode). You can specify a smaller font size, e.g. 9.5 point font
for portrait mode with the optional -F<size> argument. E.g.
On a Sun workstation
    ENTER psprint -p -ns -F9.5
On DEC Alphas
    ENTER psprint -p -ns -f9.5

-- -- Long lines in the program

If you allow lines of text in your program to get too long then they
will not print on a normal A4 sheet of paper. The print command may
either chop them off, or "wrap them round" so that bits at the right
end start on the next line. Either way it makes your program harder
to read. TRY TO AVOID MESSY PRINTOUT.

Normally for printing program text it is best if your lines are no
longer than about 75 characters wide, though you can use more characters
if you use a smaller font (but not so small that it is unreadable!)

So remember to break up long lines and indent them. For example, a long
"elseif ... then" line in a program could be broken into four lines like
this:

    elseif
        [ ..... ...... .... .....]
            matches
                [ ..... ...... .... .....]
    then

Also if you use ";;;" to put comments at the right of your code those
comments will sometimes make the lines too long so re-arrange the
comments if lines get long. E.g. put the comment on the line BEFORE the
code.

If after you have tried to improve the formatting your programs still
print out with lines wrapped, you can use ENTER psprint with a smaller
font size to print them, as explained above. But it is better to do
intelligent formatting and not produce a tiny font.

-- -- Formatting with Latex

There is a much better formatter available on our machines called Latex.
You can learn how to use it by looking at two files TEACH LATEX and
TEACH LATEX.TEX. The first gives general instructions and the second is
a sample file which you can copy and edit. Further information is in
HELP LATEX and HELP VED_LATEX.

A simpler formatter available to VED users is described in HELP RNO and
HELP VED_RNO. It can be used to produce right-justified text, page
numbers, portions of the text underlined, portions centred, and a
"header" or "footer" on every page.

-- -- Line spacing: DO NOT USE DOUBLE SPACING
Whichever mode of formatting you use for your main report (Latex, PC
word processor, Star Office, etc.) please do NOT use double spacing with
a blank line between lines of text. Double spaced text is hard to read,
wastes trees, and makes the report unnecessarily bulky. Use only single
spacing or 1.5 spacing. If you use double spacing for draft versions so
that you can easily mark corrections between lines, you should change
the spacing for the final version.

Also make sure that the margins are wide enough for stapling or binding
without making the text inaccessible.

-- How to get computer printout into your report ----------------------

Make sure you include examples of the whole system working, showing any
results or any printout produced. But do not include large amounts of
repetitive or indigestible trace printing.

One way of getting printout into a VED file is explained in TEACH LMR
(Load Marked Range). When you test a procedure and output is produced in
your 'output' file you can mark the range and copy it into your report
file (ENTER ti) , if you are using VED to write it.

The ENTER R command in VED can be used to read other files into your
report file. E.g.

    ENTER r prog.p
will read the contents of the file PROG.P into the file being edited, and
insert them immediately after the current line.

Alternatively you can use the command
    ENTER ti
to transcribe part of one file into another.
See TEACH MARK for details. A summary is in HELP MARK.

If you use Latex, you can include bits of programs or computer printout
as illustrated in TEACH LATEX.TEX, by enclosing them between:

    \begin{verbatim}

    \end{verbatim}

This stops the text being re-formatted by latex.

If you use ENTER psprint to print trace output then see the advice
above about line length and font size.

If you are using another word processor (eg. Word) for the main
report, you can leave spaces for portions printed on our computers, and
stick them in the final report. (Make sure this is done neatly, with
a suitable glue or paste.)


-- Physical presentation ----------------------------------------------

-- (1) Packaging
Make sure that your report is submitted in a form that is convenient
to read.

Do not use a clip that comes off easily. Use a stapler (available in the
School of computer science library near the photo-copier) or a proper
binder.

Make sure that the reader can turn pages easily and that the examiner
will not have to take the essay apart, or remove it from a folder or
envelope in order to read it. Don't hand in your report in a plastic
envelope with loose pages.

Do not bind your essay in some kind of package that has to be undone for
the reader to be able to turn the pages and read the text: you will
simply irritate your examiners by doing that, even if the package looks
impressive from outside.

Do NOT use a bulky folder, with thick hard sides. The examiner has to
carry away a large pile of reports and if everyone uses bulky folders
the examiner's work is made more difficult.

-- (2) Margins
Make sure that your stapling or binding does not cause some bits of the
text to be unreadable because they are too close to the margin.

Use a margin of at least 1 inch (2.6 cm) on the left, and preferably
also on the right, top and bottom.

-- (3) Use appropriate font size
Do not use tiny print. The font in your main report should be 11 or 12
point size.

If you use ENTER psprint, or the a2ps program, make sure that for the
main text you use the portrait mode (using "-p" as explained above)
which prints one page per sheet.

For your program listings you can use a smaller font with two pages per
sheet if you have a very large program, as explained above.

Make sure that the program pages are not clipped to the rest in a manner
that makes them impossible to read.

-- (4) Front page
Make sure the first page corresponds to the section on "front matter"
above.

-- (5) Cover sheet
For formal assessments you should always attach a ``cover sheet''
available from the school, and sign the declaration.

-- Spelling, grammar, etc. --------------------------------------------

Proof-read your project carefully before handing it in. Sloppy spelling,
punctuation and grammar will cause your marks to be lowered. If you are
using a word processor that includes a spelling checker USE the checker.

If you are using VED you can run the unix program "ispell". See

    HELP VED_ISPELL

on how to invoke it from VED.

If English is not your native language you are strongly advised to get
an English-speaking friend to help with proof-reading. If necessary pay
someone to help you fix your English spelling and grammar.


-- On planning a project ----------------------------------------------

If you are planning a project, the TEACH PROPOSALS file will be useful
in suggesting how to think about it before you start writing programs.

-- Plagiarism, collusion ----------------------------------------------

Plagiarism involves taking the work of another and presenting it as your
own without your acknowledging the source. Collusion involves
undisclosed collaboration, e.g. getting another student to write your
programs for your. Either can be severely penalised.

You should regard the project as primarily a LEARNING experience not an
ASSESSMENT exercise with the object of getting high marks.

For instance, getting a high mark by deception, e.g. simply copying
programs written by others, can mean that later on your deception is
exposed when you cannot perform tasks allocated to you. That can be far
more disastrous than poor marks, e.g. leading to losing your job. It's
better to learn, while you have the opportunity.

-- And finally --------------------------------------------------------

1. These are guide-lines not instructions to be obeyed rigidly at all
costs. When in doubt use your common sense and imagination. Remember
that you must keep the examiner interested, but you must also be honest
about what you have done.

2. Many people don't really start to understand programming until they
do their first project. Enjoy it and learn much!


--- $poplocal/local/teach/reports
--- Copyright University of Birmingham 2000. All rights reserved. ------