Transcript comp208-lecture09

COMP
208/214/215/216
Lecture 9
Report Writing
Report Writing
• Almost all projects involve the writing of a
report or dissertation which carries the
bulk of the marks.
• Your project will be judged on its report
– The merit of a project will not be recognised if
the report is bad
– A good, balanced, report can show a project
to its best advantage.
Before writing your report
• Consider what is required from the report
– Typically there will be clues as to what should be in
the report in the instructions or guidelines
• Consider your audience
– They can be assumed to know some things
– This will help determine the balance and what
requires detail
• Be aware of the target length
– This determines the amount of detail
– It is always possible to report a project in 1 page or in
a hundred pages.
Structuring Your Report
• I recommend a top down approach:
–
–
–
–
Chapter Headings
Section Headings
Sub-section headings
Paragraphs within sub-sections
• Examine the structure
– coverage, balance, detail
• Write the paragraphs
Of course you may change the structure as you write.
A structure permits work allocation between people,
and allows flexibility in the order of writing.
Generic Report Structure
•
•
•
•
•
•
•
•
Title Page: title, author, date, course
Abstract: a one page summary
Acknowledgements: people to thank
Contents: to sub-section level
List of figures and tables: optional
Chapters: introduction, body, conclusion
References: in proper format
Appendices: labelled A, B, etc, to give details, eg,
design diagrams, user manual.
Group Project Report Guidelines
 Your team report should be no more than 10 pages.
 It should contain:
 Details of the team members and a summary of their roles on the
project
 An overview of the application: what it does, who is intended to
use it; why they might want to use it
 A description of what was achieved on the project
 An evaluation of the strengths and weaknesses of the project
 Suggestions for future developments
 A one-page discussion of how your project related to the codes of
practice and conduct issued by the British Computer Society
 A bibliography of materials used on the project.
• Only a single “Chapter” - so straight to sections.
Sections
1.
2.
3.
4.
5.
6.
7.
Members and Roles
Application Description
What was Produced
Evaluation
Extensions
Professional Issues
Bibliography.
Sub Sections
For each section, decide what you want
to say in in each section, and the order in
which you want to say it. Example:
2. Application Description
2.1
2.2
2.3
2.4
Application Domain
Types of User
Typical Queries
Typical Reports.
Evaluation is Important
• Give a balanced, critical appraisal
• Talk about weaknesses as well as
strengths
– Better to show you recognise things that
could have been better than to pretend
everything is wonderful when it is not
• Discuss things that you would do
differently with hindsight.
Format of the Report
• Deciding on the format at the outset makes life easier when
you bring the report together
• If there are guidelines, follow them. Otherwise you need to
decide on
– Fonts: Times Roman is recommended for text;
constant width (e.g. courier) for code
– Font size: 12 recommended, no less than 10. Headings
proportionally bigger
– Use single column, justified, with reasonable margins,
with page numbers, monochrome
– Line spacing: One and half is best: single is ok; double
too much.
Style
• The style should be clear, but formal
–
–
–
–
Avoid “I” as much as possible
Keep sentences as short as possible
Avoid abbreviations and slang
Use simple words
• do not utilise esoteric or arcane terminology
– Do not use contractions (don’t, it’s, isn’t)
– Do use the past tense
– You are writing a report, not a narrative story.
Do not write stuff like
After I’d written the program I compiled it, but all I got was a lot
of errors. I tried putting everything on different lines, but it still
wouldn’t compile, so I separated out the declarations. Still no
luck. So I went to see Dave Shield and he told me that I was
running C code through a JAVA compiler, and when I used the C
compiler it did sort of compile, and after a bit I got it to run fine.
But now I found that it was giving the wrong answer so I went
to the pub. The next day I realised I’d used + when I meant * in
the relevant line and then it worked ok.
Write instead:
“The program was successfully written, compiled and debugged.
Spelling
Belonging to them
A place
• Always use a spell checker – but remember
that you may be using correct words in
incorrect places:
– there is no apostrophe in its. “It’s” is a contraction
of “it is”. “Belonging to it” is its
– They left their books over there
– “Alot” is not a word. “A lot” or “allot”
– separate is correct. seperate is not.
– Relevant is correct. Relevent is not.
much
give out
Grammar
Wrong use of comma:
either semi colon or
full stop
• Try to use correct grammar
– Do not run sentences together:
• Not “the program was a success, it did everything the
user wanted. Use a semi-colon, or start a new sentence
– Sentences have verbs in them:
• Not “There are two kinds of input device. Keyboard and
mouse.” Either one sentence:
• “There are two kinds of input device, namely keyboard
and mouse”, or put a verb in the second sentence
• “There are two kinds of input device. These are keyboard
and mouse.”
If in doubt use short sentences (with verbs)
No verb in
this “sentence”
Abstracts
• A short summary of the report or
dissertation.
• Summarise the background, approach
and results
• Not just a contents listing
• Do not use references in the abstract
• Do not use acronyms in the abstract.
Figures and Tables
• Diagrams and Tables are very useful to
help explain some things and to present
results
• All figures and tables should
– Have a number (chapter.figure). Figure 3.4
is the fourth figure of chapter three
– Have a caption eg,
• Figure 3.4: Architecture of the system.
References and Use of
Sources
• In the text refer to sources by name and date
– one author: Houndscrounger (1997)
– two authors: Mills and Boone (1967)
– three or more authors: White et al. (1994)
• Make sure you refer to your sources in the text
wherever it is appropriate to do so.
• Attributed quotation shows you know the
literature: Unattributed quotation or paraphrase
is Plagiarism.
Use Sources To:
• Give the source of any quotations, diagrams etc that you
use.
– Never use someone else’s words without citation
• To identify context
– “Many planning systems exist (e.g. Tate (1967), Lyle (1985),
Sugar and Venables (1994)).”
• To justify your claims:
– “Z-Sat is provably NP-complete (Jobsworth (1943)).”
– “It has often been said that user interfaces should be user
friendly (e.g. Diaper (1981)).”
• To provide background
– “For a fuller description of the notation, see Marley and Scrooge
(1967)).”
Bibliography
• You must give full details of every work
cited and used in the project.
• Details comprise:
– All authors and initials
– Date of publication
– Journal/Collection (for papers)
– Publisher and Place of Publication (for books)
– Page numbers (for papers).
Bibliography - Examples
• Book:
– Thom, A.W., Dick, J., and Harris, K.P., (1957). Principles and
Practice, Clarendon Press: Oxford.
• Journal:
– Lenin, V.I., (1917). Reason and Revolt, International Journal of
Computer Science, Vol. 3, No. 4. pp. 54-67.
• Collection:
– Hill, C., and Dale, W., (1998). Using Colour Effectively. In Fell,
D.R., (ed), Interface Design, Blackwell, Oxford. pp. 234-287.
• Web Site
– Castro, F. (1965). Database Design. Available from
htpp://www.fidel.cu/dbdes (25 January 2000).
– For web-sites, you should give the URL and the date you last
accessed it.
Appendices
• Use appendices to include detailed material to
substantiate the report: eg,
–
–
–
–
–
–
–
Code listings
Requirements statement
Design documents (original and revised)
Screen shots
Test data and runs
Questionnaires
User manual
• Label the appendices:
– Appendix A, Appendix B, Appendix C, etc.
User Guides
• Should include:
–
–
–
–
–
–
Overview of software: what it does; who it is for
hardware requirements
how to install the software
how to run the software
how to use the software
how to quit
• Write in terms appropriate to target user.
Summary
• Think about the structure
• Use a consistent, appropriate layout
• Write clearly, in a formal style, using
correct grammar and spelling
• Cite all your sources
• Give full details of the sources in the
bibliography
• Make sensible use of appendices.
Final Deliverables
• Portfolio (one per team)
– See Lecture 8 for details
• Group Non-plagiarism Declaration (one per team)
• Individual Submission (one per student)
– A statement of what you (personally) have learnt (1-2 pages)
– A completed Peer Assessment form
– Form available from the module web-pages