comp208-lecture09-writing - cgi.csc.liv.ac.ukcgi.csc.liv.ac.uk/~comp208/2018/comp208-lecture09-writing.pdf · constant width (e.g. courier) for code –Font size: 12recommended, no

COMP 208/214/215/2162017-18

Lecture 9Academic Writing

Final Project Deliverables• Portfolio (one per team)

– See Lecture 8 for details

• Group Non-plagiarism Declaration (one per team)– Available in paper form from the CS Helpdesk.– It should be filled and signed by all group members BUT CAN BE SIGNED BY

THE GROUP REP ON BEHALF OF THE REST OF THE TEAM, and scanned (to be returned in SOFT format)

• 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

• All this due: 12 noon, Friday 2018-05-11

Advise

• Writing a GOOD report takes time• Remember that the readers do not have

the same background as the authors

Academic Writing• Almost all projects involve the writing of a

report or dissertation which carries the bulk of the marks.

• A max of 30% of the available project mark based on the project Portfolio– The merit of a project will not be recognised if

such report is bad– A good, balanced, report can show a project

to its best advantage.

PLAN

Before Writing• Consider what is required

– Typically there will be clues as to what should be in the document 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• Top down approach. Decide:

– Chapter Headings– Section Headings– Sub-section headings– Paragraphs within sub-sections

• Write the paragraphsOf course you may change the structure as you write.A structure permits work allocation between people,and allows flexibility in the order of writing.

Structuring Checks• After first draft examine the structure

– Coverage: check that everything is there– Detail: check that things are mentioned with the right level of

detail– Balance: all chapters should have approximately the same

length.

EXAMPLE 1 (GOOD?): chapter 1 (10 pages); chapter 2 (30 pages); chapter 3 (38 pages); chapter 4 (21 pages); appendix (40 pages)

EXAMPLE 2 (BAD?): chapter 1 (10 pages); chapter 2 (24 pages); chapter 3 (78 pages); chapter 4 (6 pages); appendix (3 pages)

Generic 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 theproject

• An overview of the application: what it does, who is intended touse 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.

Sections1. Members and Roles2. Application Description3. What was Produced4. Evaluation5. Extensions6. Professional Issues7. Bibliography.

Sub SectionsFor 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 Description2.1 Application Domain2.2 Types of User2.3 Typical Queries2.4 Typical System Output

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 a Written 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 likeAfter I’d written the program I compiled it, but all I got was alot 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• 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.

Belonging to them A place

much give out

Grammar• 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.”

Wrong use of comma:either semi colon orfull stop

No verb in this “sentence”If in doubt use short sentences (with verbs)

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 explain some things and to

present results• All figures and tables should

– Have a number (chapter.figure). Figure 3.4is the fourth figure of chapter three

– Have a caption eg, • Figure 3.4: Architecture of the system.

Figures and Tables

1. EXPLAIN THEM!2. DO NOT USE A FIGURE OR

TABLE **INSTEAD OF** A TEXTUAL DESCRIPTION.

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 excerpts– Requirements statement– Design documents (original and revised)– Additional Screen shots– Additional Test data and Runs– Questionnaires (if used, for instance in

testing/evaluation)• 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.

PLAN