Writing

Technical writing Structure Referencing Writing Style Tools Metrics

CS351 - Software Engineering (AY2004)3 Structure Abstract –high level summary - wild claims Introduction –expanded abstract - forward references Body –the main points, in depth Conclusions –summary of main results References –where your citations come from.

CS351 - Software Engineering (AY2004)4 Abstract High level summary –what the document is about, –it highlights the theme of the document. Mostly introduction and broad summary of results, –be careful of wild claims, –the document has to live up to the abstract. An abstract may be optional, –write one anyway to get your ideas straight.

CS351 - Software Engineering (AY2004)5 Introduction Expansion on the abstract, States the important points, –give some context for each, –follow the theme, –makes the document interesting.

CS351 - Software Engineering (AY2004)6 Body In depth explanation of important points, –deal with main points in order, –add explanatory sections as required, –give as much depth as the theme requires, –stick to the point. Linkage –the introduction should flow into the body, –the sections should not appear isolated.

CS351 - Software Engineering (AY2004)7 Conclusions Summarise –why the main points were important, –what was really demonstrated, –where is this all leading, –stick to the point.

CS351 - Software Engineering (AY2004)8 Referencing style References should be cited when –Introducing a new concept, term, system,... –Place reference at the end of the term, concept, sentence. References in the body –[x] where x is a number, or inits++year –examples [bro95], [1], [4,6], [bro95a,bro95b] References section –[x] Surname, Inits,...., Title, Where to find it, year,page nums.

CS351 - Software Engineering (AY2004)9 Writing style Brackets () for asides, –replace these with commas, –better still, rewrite the sentence so that arent required. Reread sentences your work to see that it makes sense. Have someone else review your work, –they should pretend to be naive, –“what does this mean?”, “I don’t understand” –forget your ego!

CS351 - Software Engineering (AY2004)10 Tools Use grammer and spelling checkers. Spell checking picks up non-words, –it doesn’t mean the spelling is correct. Grammar checkers pick up some obvious errors, –sentences without verbs, repeat words, obscure language,.... –they may not suit your document type.

CS351 - Software Engineering (AY2004)11 Writing metrics Readability measures –some systems can also score your style, –average sentence lengths. Scores are based on grammar analysis, –year 8 is the target, –technical documents tend be to year 12 or later, –why? it is hard to be definitive and technically correct.

CS351 - Software Engineering (AY2004)12 Public speaking Where to start Structure Construction

CS351 - Software Engineering (AY2004)13 Where to start A clear statement of intention, –essential to keep it simple and to the point, –focus is everything (almost). Be prepared, Be comfortable - humour if you can do it, Be interesting - understandable, up to date, Be committed - believe in it.

CS351 - Software Engineering (AY2004)14 The proposition You start with a subject, –too broad - but a start. Define a theme, –specific aspect of the subject being presented. Define a proposition, –the focus of the presentation.

CS351 - Software Engineering (AY2004)15 Structure Introduction –state the theme - show its relevance, –introduce the main points, –write this last, Main Points, Conclusion.

CS351 - Software Engineering (AY2004)16 Main points Main points all support the theme, –3 or possibly 4, –repetition to help it stick. Sub-points, –to clarify, expand, illustrate, apply each main point, Length –by elaboration of the main points, –30-40 minutes is easy, –you only have 5 minutes.

CS351 - Software Engineering (AY2004)17 Conclusion Summarise and challenge. Structure, –restate main points, stress title, –restate application of main points, –optional illustration to make aim or purpose clear, –appeal. Appeal to –desire, duty, fear, OR –deal with objections.