Writing CS 351 Software Engineering AY 2004 Technical

Writing CS 351 - Software Engineering (AY 2004)

Technical writing Structure Referencing Writing Style Tools Metrics CS 351 - Software Engineering (AY 2004)

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. CS 351 - Software Engineering (AY 2004) 3

Abstract • High level summary – what the document is about, – it highlights 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. CS 351 - Software Engineering (AY 2004) 4

Introduction • Expansion on the abstract, • States the important points, – give some context for each, – follow theme, – makes the document interesting. CS 351 - Software Engineering (AY 2004) 5

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

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

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 [bro 95], [1], [4, 6], [bro 95 a, bro 95 b] • References section – [x] Surname, Inits, . . , Title, Where to find it, year, page nums. CS 351 - Software Engineering (AY 2004) 8

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! CS 351 - Software Engineering (AY 2004) 9

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. CS 351 - Software Engineering (AY 2004) 10

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. CS 351 - Software Engineering (AY 2004) 11

Public speaking • Where to start • Structure • Construction CS 351 - Software Engineering (AY 2004) 12

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. CS 351 - Software Engineering (AY 2004) 13

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. CS 351 - Software Engineering (AY 2004) 14

Structure • Introduction – state theme - show its relevance, – introduce the main points, – write this last, • Main Points, • Conclusion. CS 351 - Software Engineering (AY 2004) 15

Main points • Main points all support 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. CS 351 - Software Engineering (AY 2004) 16

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. CS 351 - Software Engineering (AY 2004) 17