Report Writing Tomas Maul nottingham edu my Based on

Report Writing Tomas. Maul@nottingham. edu. my Based on material from G 52 GRP 1 School of Computer Science G 52 GRP

Layout of Slides q General tips on writing reports. q Principles, practices and guidelines for technical writers. 2 School of Computer Science G 52 GRP

Report Structure - Front Page q Your reports should have a front page containing the following: Ø Ø Ø Ø Notes based on the “report writing” lecture for G 52 GRP. Your name Your supervisor’s name Your project title Your group name (e. g. ajt-xyz 1) This is for a Software Engineering group project module. Details may vary for other Your group members’ names disciplines. The date Whether the report is final/interim and group/individual 3 School of Computer Science G 52 GRP

Report Structure - Sections q Reports should be broken down into sections and maybe subsections q There should be: Ø Ø Ø Ø Introduction This is for Software Engineering. Background Details may vary for other System Design disciplines. Results Evaluation Peer Assessment Discussion and Conclusion Bibliography 4 School of Computer Science G 52 GRP

Referencing Information (1) q Facts or research stated in the text of the reports should be clearly referenced q For example: Ø Ø [Smith and Jones, 1999, page 45] for a book [Bloggs et. al. , 1998] for a research paper [http: //www. cs. nott. ac. uk/Research/blah. html] References to books/papers/web pages etc should be listed in the bibliography 5 School of Computer Science G 52 GRP

Referencing Information (2) q You can quote pieces of text from other sources provided: q The quoted text is placed within quote marks q The quoted text is not too long (not longer than one or two paragraphs maximum) q You state clearly where you took the text from(for books, give the page number too) q If you need to include longer pieces of text then put it in an appendix and say where it is from 6 School of Computer Science G 52 GRP

Plagiarism q Plagiarism is viewed as a very serious offence q Plagiarism includes copying from other students, books, research papers, the web, etc. q If you are suspected of plagiarism you will get 0 marks q You must write your reports in your own words! 7 School of Computer Science G 52 GRP

Writing Tips – Initial Brainstorm q Before starting to write … q Before even settling on a report layout … q Brainstorm your report: Ø Write down all the things you want to talk about regardless of order. Ø If you are doing group brainstorming, remember: o Do not shoot down any ideas. o Initially, all ideas are valid. Initially: quantity not quality. Ø After the initial brainstorm, then start to cluster and order ideas. Some will be repetitions, others will be incomplete. Ø Once the ideas have been organized and refined then you can move onto the report layout. 8 School of Computer Science G 52 GRP

Writing Tips – Constant Refinement (1) q Breaking writer’s block. q Write as though your life depended on it. Just start. q Go back repeatedly until you are satisfied. q Everything can be improved. Some authors don’t accept a sentence until it has been rewritten 5 times. q Give yourself enough time. “Last minute” will not work. 9 School of Computer Science G 52 GRP

Writing Tips – Constant Refinement (2) q The ultimate objective is to communicate. q The refinement process involves optimizing several factors, including: Ø Ø Clarity and fluidity. Succinctness. Accuracy. Grammatical correctness. 10 School of Computer Science G 52 GRP

Writing tips - Read q If you want to improve your writing, first improve your reading. q The more you read (well written books, articles, etc. ), the more you will internalize good writing styles, vocabulary, grammar, argumentation styles, structures, etc. q Quite often, it is good to have one particular text (book, report, article) as a fundamental reference. Ø The quality of that text can be used as a benchmark for the quality of your text. 11 School of Computer Science G 52 GRP

Writing Tips - Argumentation q Be aware of underlying arguments and assumptions. q The real engine of any scientific text lies in the argumentation. q If your argumentation is weak or repetitive this will tend to frustrate the reader. q Make sure you know what your main arguments are and try to make them as strong as possible. q If you have a central argument that you tend to repeat, then at least “repeat it” from different perspectives, using different evidential sources, etc. 12 School of Computer Science G 52 GRP

Writing Tips - Clarity q Probably the most important factor. q If your reader can’t understand what you are writing … q Why the lack of clarity? Ø Incompleteness? Ø Bad grammar or style? Ø Lack of understanding? q Relativity. What is your audience? q Test your work (or parts of it) on representative elements of your target audience. 13 School of Computer Science G 52 GRP

Writing Tips - Grammar q Don’t ignore this aspect. q This factor has a very strong impact on clarity. q It will also reflect your level of commitment. q Even if English is not your first language, you are expected to find ways to deliver on this aspect. Some options: Ø Grammar resources (e. g. English usage, etc. ) Ø Automated grammar tools (but be very careful with these). Ø Proof-reading: o Professional. o Swap sections among the group members for proof reading. Ø Self-improvement. 14 School of Computer Science G 52 GRP

Writing Tips – Art of Writing q Where science meets art. q How to be clear AND engaging or even inspiring? q It is hard to exactly quantify all aspects that make a great piece of science writing. Ø There are concrete and tangible elements, but there also certain intangible ingredients that may be crucial. q These intangible aspects usually only come after persistent practicing. q The art is in hiding the art. q Minimize verbiage, e. g. : Ø "It is clearly evident from Fig. 1 that bird species richness increased with habitat complexity". Ø "Bird species richness increased with habitat complexity (Fig. 1)". 15 School of Computer Science G 52 GRP

Writing Tips - Editor q Appoint an Editor: If in a group. Ø Overall responsibility for document Ø Integrates contributions from all other writers Ø Ensures consistency (typesetting, layout, style of figures, language, etc. ) and cohesiveness (that everything fits together). q Editor should not be expected to do “all the work”: each writer should be prepared to edit their contributions until the Editor approves content, style, length, . . . q While Editor shouldn’t be a “dictator”, investing him/her with a fair amount of power in editorial questions is likely a good idea. 16 School of Computer Science G 52 GRP

Writing Tips - Typesetting & Layout q Keep it simple q Number chapters, sections, figures, examples, pages. q Include a table of contents. q Use typographical devices like lists where relevant. q Adopt proper typographical conventions. E. g. : Ø Ø Correct typesetting of mathematics Program code and code fragments in a type writer font. Use italic (or possibly bold) for emphasis. Don’t underline headings. Ugly! q To achieve truly professional results with relative ease, consider using La. Te. X (somewhat steep learning curve). 17 School of Computer Science G 52 GRP

Writing Tips – Misc. q Do use pictures, diagrams, examples to help getting your message across. (But avoid gratuitous decoration!) q Keep your writing focused! Ø Make sure everything you include is necessary and relevant. q Do use appendices for bulky material that are mainly needed for reference. 18 School of Computer Science G 52 GRP

Principles, practices and guidelines q The following principles, practices and guidelines for technical writers were extracted from Norman Ramsey’s paper: Ø “Teach Technical Writing in Two Hours per Week”. (from Norman Ramsey’s homepage) 19 School of Computer Science G 52 GRP

Principles (1) q Correctness. Ø Correct spelling and grammar are essential but remember that you have more flexibility than your high-school English teachers may have given you. q Consistent names. Ø Refer to each entity (e. g. algorithm, theory, concept) with the same name throughout the text. If you need to introduce new terminology (e. g. the name of your system) do this carefully (simple, meaningful and catchy names are preferable). q Subjects and verbs. Ø Identify the main “characters” in your text. Assign these “characters” to subjects, and their main functions to associated verbs. q Information flow. Ø In general, don’t repeat information or return to old information as you progress in the text. Follow old information with new information. Create a flow whereby the reader is continuously introduced to new information. This is a general rule. Sometimes old information needs to expanded on at a later section. 20 School of Computer Science G 52 GRP

Principles (2) q Emphasis. If you want something in particular to be emphasized (because of relevance or in order to be recalled more easily), put it at the end of the sentence (or paragraph). q Coherence. In a coherent passage, choose subjects that refer to a consistent set of related concepts and mention them in a clear linear manner, e. g. : place known information at the beginning of the sentence and novel information at the end of the sentence. q Parallel structure. Provide definitions and order your text so that the similarities and differences between concepts can be easily apprehended. Detect potential ambiguity and eliminate it. q Abstract. Assume this is the only thing people will ever read of your paper. What material satisfies the largest number of readers of your abstract? What is the essential information in your paper? 21 School of Computer Science G 52 GRP

Practices (1) q In most cases, it is better to write small amounts consistently (every day), rather than large amounts irregularly. q Initially, it is better to focus on the process rather than the product. Measure your performance in terms of how consistently you write and apply good writing practises, rather than the quantity & quality of your output. q Prewrite. Think before you write. Think, think. Jot down notes. Brainstorm. Sketch diagrams. q Use index cards. These can be useful for organizing your initially disjointed ideas. Other techniques can be used: whatever helps in creating order out of the initial chaos. 22 School of Computer Science G 52 GRP

Practices (2) q Write a “rubbish” first draft. The value of a first draft lies not in that the work is complete or perfect, but that it can be used as a starting point for successive refinement. q Don’t worry about page limits. Write the ideal paper that you would like to write, and then shrink it to the target size. Ø Another option is to write the shortest paper possible that communicates your message and then expand it as necessary. Different strategies suit different temperaments. q Cut. Plan a revision session in which your only goal is to cut. Ø Or: plan a revision session in which your only goal is to determine which parts you will expand. 23 School of Computer Science G 52 GRP

Guidelines (1) Explaining a Technical Concept q Have the properties of the entity been adequately listed and explained? q Have the listing & explanation been qualified (e. g. completeness)? q Has each property been adequately named (e. g. according to conventions)? Has the correct notation been used? q Have the relationships between properties been properly listed and explained? What elements condition whether and how these relationships hold? 24 School of Computer Science G 52 GRP

Guidelines (2) Checklist for Technical Exposition q Have you identified your target audience? q Did you inform the reader of your expectations (e. g. level of knowledge)? q Do you have examples? Is every general, abstract declaration illustrated by an example? q Is every concept mentioned before it is used? Are most concepts defined before use? Is all notation clearly explained? q Do you make use of pedagogical simplifications in order to explain complex concepts? q Do you know what (expositional, notational, etc. ) style you are using? Are your definitions and examples all consistent with that style? 25 School of Computer Science G 52 GRP

Useful Resources Links: • www. columbia. edu/cu/biology/ug/research/paper. html • www. oup. com/us/samplechapters/0841234620/? view=usa • http: //www. cs. tufts. edu/~nr/pubs/two-abstract. html Recommended reading: • Lyn Dupré. BUGS in Writing: A Guide to Debugging Your Prose. Addison Wesley, 1998. 26 School of Computer Science G 52 GRP

Acknowledgements q V. P. Kallimani q Henrik Nilsson q Norman Ramsey 27 School of Computer Science G 52 GRP