1. CSE1204 - Information Systems 1 Communication and Documentation: Additional Notes on Written Reports

2. 2 Written reports for a defined audience for a defined audience about a defined topic about a defined topic in a defined format in a defined format They are They are permanent permanent authoritative authoritative detailed detailed

3. 3 Classes of reports Development or Project reports Development or Project reports by-products of a process by-products of a process Production reports Production reports principal products of an application system principal products of an application system Academic reports Academic reports principal products of an enquiry process principal products of an enquiry process

4. 4 Development reports by-products of a process by-products of a process produced irregularly produced irregularly at milestones rather than periodically at milestones rather than periodically required opportunistically required opportunistically only produced if circumstances require it only produced if circumstances require it four classes of report four classes of report

5. 5 Report types technical reports technical reports how to do something how to do something analytical reports analytical reports why something happened/will happen why something happened/will happen status reports status reports how well things are going how well things are going proposals proposals speculations about, or justifications for action speculations about, or justifications for action

6. 6 Report structure Letter of transmittal Letter of transmittal Cover page Cover page Table of Contents Table of Contents Management Summary Management Summary Introduction Introduction Body of report Body of report Recommendations Recommendations Appendices Appendices

7. 7 Letter of Transmittal tells the requesting authority of report completion tells the requesting authority of report completion identifies the report identifies the report identifies the author(s) identifies the author(s) references the authorising document references the authorising document enumerates the report components enumerates the report components

8. 8 Cover page Report Title Report Title Sponsoring organisation Sponsoring organisation Authors Authors Authors' affiliation Authors' affiliation Date and Version Date and Version

9. 9 Table of Contents Sequential list of sections and topics Sequential list of sections and topics a navigation aid to the report a navigation aid to the report Number, Heading, page number Number, Heading, page number left and right justified left and right justified

10. 10 Management Summary half to one page in length half to one page in length highlights the important decisions highlights the important decisions identifies: identifies: total costs total costs total time required total time required management action needed management action needed benefits and liabilities benefits and liabilities

11. 11 Introduction sets the scope of the report sets the scope of the report references the authorising decision references the authorising decision defines the objective of the report defines the objective of the report defines the background to the report defines the background to the report references methods and techniques used references methods and techniques used

12. 12 Body of the report the substantive work is reported here the substantive work is reported here divided into numbered chapters or sections divided into numbered chapters or sections within sections, topic-related paragraphs within sections, topic-related paragraphs section, sub-section, paragraph headings section, sub-section, paragraph headings hierarchical numbering hierarchical numbering use figures, pictures and tables for explanation use figures, pictures and tables for explanation

13. 13 Paragraph content technical and status reports technical and status reports facts only facts only analytical reports analytical reports facts and recommendations (professional opinion) facts and recommendations (professional opinion) proposals proposals professional opinions, excuses, rational speculations professional opinions, excuses, rational speculations

14. 14 Graphics support images convey information too images convey information too images can transcend language and culture images can transcend language and culture words must be interpreted in a context words must be interpreted in a context images are thought to be objective (but may not be) images are thought to be objective (but may not be) higher information density in images than words higher information density in images than words colour and scale influence interpretation colour and scale influence interpretation

15. 15 Recommendations only included when specifically asked for only included when specifically asked for usually only for analytical and proposal types usually only for analytical and proposal types justifications refer to report sections justifications refer to report sections supporting data as Appendices supporting data as Appendices

16. 16 Use of reports written reports for formal communication written reports for formal communication professional staff are always reporting professional staff are always reporting some things always change: some things always change: requirements requirements users users tools and platforms tools and platforms budgets ……. budgets ……. version control is critically important version control is critically important

17. 17 Report aesthetics visual presentation style visual presentation style is it easy to look at? is it easy to look at? writing style writing style is it easy to understand? is it easy to understand? report structure report structure is it easy to use? is it easy to use? successful reports answer YES to all successful reports answer YES to all

18. 18 Specify the document Draft and edit the document Review the document Publish the document Maintain the document Not OK OK The Documentation Process

19. 19 Specify the Document Conceptual decisions Conceptual decisions Break documentation down by task Break documentation down by task Use a minimalist design Use a minimalist design Develop a concept of audience Develop a concept of audience Identify the purpose for each document Identify the purpose for each document Physical decisions: Physical decisions: Organise the documentation Organise the documentation Choose appropriate media Choose appropriate media Decide on typography, layout, colour and page size Decide on typography, layout, colour and page size Implementation decisions: Implementation decisions: Plan for updating, Develop a cost/time schedule Plan for updating, Develop a cost/time schedule

20. 20 Draft and Edit the Document Overcome writer's block Overcome writer's block Be aware of how readers read Be aware of how readers read Use reader-based writing techniques Use reader-based writing techniques Use an appropriate document format Use an appropriate document format Create your reference aids Create your reference aids Develop effective graphics Develop effective graphics

21. 21 Overcome Writer’s Block Internal writer's block Internal writer's block Be prepared to write poorly and edit well Be prepared to write poorly and edit well Don't feel you have to start at the beginning... start where you feel most comfortable Don't feel you have to start at the beginning... start where you feel most comfortable Tape what you want to tell them... transcribe it and then edit Tape what you want to tell them... transcribe it and then edit Stop in the middle of a section at the end of a day... makes it easier when you get back to it Stop in the middle of a section at the end of a day... makes it easier when you get back to it External writer's block External writer's block Become an expert on the subject matter Become an expert on the subject matter Give sources enough time to prepare Give sources enough time to prepare Offer sources a variety of ways of getting information to you Offer sources a variety of ways of getting information to you Use management leverage Use management leverage

22. 22 Review the Document Purpose - to let users try it out to see whether it is effective and can stand alone Purpose - to let users try it out to see whether it is effective and can stand alone Layout - it can just be in draft form Layout - it can just be in draft form Coversheet - the users should know the duration of the review, and how to return their comments to the authors Coversheet - the users should know the duration of the review, and how to return their comments to the authors Feedback - let the users know how their comments were used.. provide them with a summary report Feedback - let the users know how their comments were used.. provide them with a summary report

23. 23 Publish the Document Planning - make sure printers know the type of work you are giving them and are ready for it Planning - make sure printers know the type of work you are giving them and are ready for it Deadlines - leave plenty of time for this stage... it can take up to 25% of the documentation effort Deadlines - leave plenty of time for this stage... it can take up to 25% of the documentation effort Clarity -the clearer your production instructions the better your final product Clarity -the clearer your production instructions the better your final product

24. 24 Maintain the Document Maintain a master copy of the document that notes all corrections and updated information; Maintain a master copy of the document that notes all corrections and updated information; Date each correction and change and the reason for it; Date each correction and change and the reason for it; Version control is important; Version control is important; Maintain a document distribution list... make sure that the user acknowledges that they have received the updates and have updated their document. Maintain a document distribution list... make sure that the user acknowledges that they have received the updates and have updated their document.

25. 25 Updating is a fact of life. All technical documents must cater for updating Hints on Maintenance Binding Binding large, updated often.. ring binding large, updated often.. ring binding small.. easier just to reissue small.. easier just to reissue Section numbering schemes Section numbering schemes allow individual sections to be replaced allow individual sections to be replaced with page numbering all pages would have to be renumbered and replaced with page numbering all pages would have to be renumbered and replaced Version numbers and update dates on document. Version numbers and update dates on document. Change bars Change bars Reader comment sheets Reader comment sheets Update checklists.. lists all areas of a document that need to be changed if any one section changes Update checklists.. lists all areas of a document that need to be changed if any one section changes Author and production notes.. lists any special methods used in writing or producing the document Author and production notes.. lists any special methods used in writing or producing the document

26. 26 References DWYER, J. (1997) The Business Communication Handbook (4 th edition) Prentice-Hall, New York, N.Y. DWYER, J. (1997) The Business Communication Handbook (4 th edition) Prentice-Hall, New York, N.Y.