Technical writing Neil Ghani ngcis strath ac uk

Technical writing Neil Ghani ng@cis. strath. ac. uk 1

Introduction • In this lecture we look at writing software reports • How to structure a basic report • What not to do • In this class 32% of marks are for the report – 2% initial practical – 30% final practical • You will have covered some of this stuff before 2

Standard report • An example will be given at • https: //www. cis. strath. ac. uk/~ng • Several sections • for larger work use chapters • Usually almost all your detailed work is consigned to appendices • This means code listing, test data… 3

Format • Format for reports – – – – – Introductory material Section 1. Introduction (problem) Section 2. Related Work Section 3. Design Section 4. Implementation Section 5. Testing & Evaluation Section 6. Future Development Section 7. Management review Section 8. Summary conclusion • S 1 -S 7 10 -15 pages in some sensible style 4

Appendices • The following appendices are standard – I. References – II. Test Material – III. User Manual – IV. Code • Also – For this class, any sensible, cheap binding will suffice 5

Introductory material (title page) • Title Page – Here • Class Number and Name (52. 222 Programming project) • Project Name • Your Name, Registration Number and Degree Course • Date of submission • A signed statement that it's all your work unless marked to the contrary 6

Introductory material (abstract) • Abstract – Typically, 200 -300 words – Perhaps something like (but not exactly) this • "This report outlines the design and development of a computer software system to. . . The program was written in C++ to run under the Unix operating system on. . . The design and ensuing program are modular in nature and make maximum use of abstract data types and of software re-use. Particular attention is paid to. . . The report includes a full user manual, as well as the whole of the code that was written. " 7

Introductory material (abstract) • The abstract describes – The purpose of the system – Its status (does it work, if not what does not) – Any limitations (e. g. only runs on Unix, only deals with English) • The abstract does not describe any detail – Data structures used – Details on implementation – Individual tests or testing strategies used 8

Introductory material (contents) • Contents Page – 1. Introduction • • 1. 1 The problem statement 1. 2 Description of the software Etc. Not obligatory for this class • Except… – Separate tables of contents, figures, equations, tables 9

Section 1 - problem definition • Introduce the problem • as defined in the real world • “why is this system necessary? ” • “what is the system is required to do? ” – Specification given (in your own words) – Additional details/specification • It may be appropriate to mention languages and target machines – If solution is restricted to particular machine/unusual choice of language • Finally summarise the functional and (any) non-functional requirements 10

Section 2 – related work • For this class we may ignore this • In general this section describes – Attempts to do similar (but not identical) things • And why our solution is better – Attempts to do exactly the same thing • Why they failed, and we will succeed – More detailed background on why this system is needed • The introduction talks in general, related work talks specifically 11

Section 3 – design • Design section is an overview of the system – What the system does without the details of how it does it – discusses the system without reference to the actual (detailed) code – break down the design – start at the top, refine to the component level – General approach – for each function outline the input, processing, output – Input – what input does the user give, how does the user provide it, – Processing – what does the system do with the input – Mention here any major data structures – Output – what output does the user get 12

Section 3 - design • may develop particular points of importance or of difficulty • Anything unusual about your system • covers general techniques, for example use of defensive programming, graphical interfaces, etc. • why you designed your system in this way 13

Section 4 - implementation • Implementation can either • explain everything slightly generally • skip the easy bits, but explain some parts right down to code level • Try to map the implementation section to the design section • Easier to read and understand • Describe each class • Describe input, processing, output – But give code details of how input is processed, etc – Which classes, named methods, describe important algorithms • Diagrams and examples almost always help 14

Section 5 – testing/evaluation • Two subsections – testing and evaluation • Testing (main) • Explain how you know that your program works correctly • For each piece of code you test – Say what you are testing – Give input, predicted output, actual output – Summary – what the test shows (working/not working, if not working why not) • Large test cases are given in detail in appendix • Small test cases are given in report • Evaluation (short) • Your evaluation or assessment of your system – Are you happy? – Could some things be done better/faster/more simply? 15

Section 6 – future work • Future development • the chance to cover the bits you would like to do differently? • the bits you didn't get right? • genuine possibilities for extension? 16

Section 7 – management review • Put original plan (textual/diagrammatic) • In this section review your assessment of your plan • Credit for • being honest • being aware of continual planning • No credit for • making it all up at the last minute 17

Section 8 - conclusion • Conclusion – "This report has described the successful design and development of. . . " – Similar to abstract but always should describe • What program does • Its status – what works and what doesn’t (briefly) – Main difference from abstract • Abstract – reader knows nothing • Conclusion – reader knows everything – Conclusion can be more specific 18

Appendices – References/bibliography • References • Any information you used explictly mention in the text • Preferably using one of the two standard systems – ‘improving the retrieval of relevant information [SB 90]. ’ or – ‘Using material from the Programming techniques course [1]’. » [SB 90] G. Salton and C. Buckley. Improving retrieval performance by relevance feedback. Journal of the American Society for Information Science. 41. 4. pp 288 -297. 1990. » [1] P. Goldfinch. Lecture notes for Programming techniques. http: //…. • Bibliography • List of material used but not mentioned in text – Java books, etc. 19

Appendices – user manual • User Manual – instructions on how a user should operate your system – Without reading the report – include locations of relevant program files! – assume a competent machine user – Don’t explain what a mouse is – but do tell them how to run the program! – give illustrations of possible inputs and corresponding outputs – cover all possible program responses – although this can become difficult for big programs 20

Appendices - code • Code – should you include it all? • yes – with comments – remember that in the report your code is merely an appendix, even though the report could not have been written without it! 21

Tips • Reports should be shorter rather than longer • but the shorter they are (if complete!) the longer they take to write • e. g. 3 weeks for 50 pages of final honours report! • Specific tip for report writing • keep systematic note of all design decisions, however trivial • distinguish yourself from the non-expert • by including intellectual activity 22

What to do… • Aim is to explain – Design decisions – Major implementation structures • Adts, class structures, interrelationships between modules and classes – Status of system • So that someone else can… – Fix, extend or modify your system (easily) – Re-construct your system (assuming basic knowledge) 23

Style • Write succinctly • don’t use first person – “I decided…”, “we implemented” • A report is not a personal statement • A report is a description of a piece of software • Look at good examples of technical writing in computing journals (in library) 24

But… • But your reports - all reports – Must be typed – Must be grammatical – Must have correct spelling 25

And… • Spelling checkers are a boon, but are far from infallible. . . • Moral? Read and correct your text again, some hours after you'd finished it! • (get a partner/parent/friend to read it) • Could you understand it if you hadn’t written it? ? 26

What not to do… • DO NOT assume the reader knows the background – Don’t assume the reader knows what you know – You can assume basic stuff • Java, arrays, integers – But not more complex stuff • Do (!) explain binary (search) trees – these are created not standard 27

What not to do… • DO NOT write a diary (please!) • ‘I wasn’t sure how to code this module so I tried…this didn’t work so I changed this line to read…Finally, I woke up in the middle of the night and realised…’ • You are describing a finished system not the process by which you developed it • DO NOT describe the code line-by-line • Unless it is stunningly original or interesting 28

What not to do… • DO NOT have paragraphs that are three pages long – Use white space • DO NOT make it complicated – Keep it simple • DO NOT forget that a happy marker is a generous marker! 29