CSE1204 - Information CSE1204 - Information Systems 1Systems 1

Communication andCommunication and

Documentation:Documentation:

Additional Notes on Written ReportsAdditional Notes on Written Reports

22

Written reportsWritten reports

for a defined audiencefor a defined audienceabout a defined topicabout a defined topic in a defined formatin a defined formatThey areThey are

permanentpermanentauthoritativeauthoritativedetaileddetailed

33

Classes of reportsClasses of reports

Development or Project reportsDevelopment or Project reportsby-products of a processby-products of a process

Production reportsProduction reportsprincipal products of an application systemprincipal products of an application system

Academic reportsAcademic reportsprincipal products of an enquiry processprincipal products of an enquiry process

44

Development reportsDevelopment reports

by-products of a processby-products of a processproduced irregularlyproduced irregularly

at milestones rather than periodicallyat milestones rather than periodically required opportunisticallyrequired opportunistically

only produced if circumstances require itonly produced if circumstances require it four classes of reportfour classes of report

55

Report typesReport types

technical reportstechnical reportshow to do somethinghow to do something

analytical reportsanalytical reportswhy something happened/will happenwhy something happened/will happen

status reportsstatus reportshow well things are goinghow well things are going

proposalsproposalsspeculations about, or justifications for actionspeculations about, or justifications for action

66

Report structureReport structure

Letter of transmittalLetter of transmittalCover pageCover pageTable of ContentsTable of ContentsManagement SummaryManagement Summary IntroductionIntroductionBody of reportBody of reportRecommendationsRecommendationsAppendicesAppendices

77

Letter of TransmittalLetter of Transmittal

tells the requesting authority of report tells the requesting authority of report completioncompletion

identifies the reportidentifies the report identifies the author(s)identifies the author(s) references the authorising documentreferences the authorising documentenumerates the report componentsenumerates the report components

88

Cover pageCover page

Report TitleReport TitleSponsoring organisationSponsoring organisationAuthorsAuthorsAuthors' affiliationAuthors' affiliationDate and VersionDate and Version

99

Table of ContentsTable of Contents

Sequential list of sections and topicsSequential list of sections and topicsa navigation aid to the reporta navigation aid to the reportNumber, Heading, page numberNumber, Heading, page number left and right justifiedleft and right justified

1010

Management SummaryManagement Summary

half to one page in lengthhalf to one page in lengthhighlights the important decisionshighlights the important decisions identifies:identifies:

total coststotal costs total time requiredtotal time requiredmanagement action neededmanagement action neededbenefits and liabilitiesbenefits and liabilities

1111

IntroductionIntroduction

sets the scope of the reportsets the scope of the report references the authorising decisionreferences the authorising decisiondefines the objective of the reportdefines the objective of the reportdefines the background to the reportdefines the background to the report references methods and techniques usedreferences methods and techniques used

1212

Body of the reportBody of the report

the substantive work is reported herethe substantive work is reported heredivided into numbered chapters or sectionsdivided into numbered chapters or sectionswithin sections, topic-related paragraphswithin sections, topic-related paragraphssection, sub-section, paragraph headingssection, sub-section, paragraph headingshierarchical numberinghierarchical numberinguse figures, pictures and tables for use figures, pictures and tables for

explanationexplanation

1313

Paragraph contentParagraph content

technical and status reportstechnical and status reports facts onlyfacts only

analytical reportsanalytical reports facts and recommendations (professional opinion)facts and recommendations (professional opinion)

proposalsproposalsprofessional opinions, excuses, rational professional opinions, excuses, rational

speculationsspeculations

1414

Graphics supportGraphics support

images convey information tooimages convey information too images can transcend language and cultureimages can transcend language and culture

words must be interpreted in a contextwords 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 wordshigher information density in images than wordscolour and scale influence interpretationcolour and scale influence interpretation

1515

RecommendationsRecommendations

only included when specifically asked foronly included when specifically asked forusually only for analytical and proposal typesusually only for analytical and proposal types justifications refer to report sectionsjustifications refer to report sectionssupporting data as Appendicessupporting data as Appendices

1616

Use of reportsUse of reports

written reports for formal communicationwritten reports for formal communicationprofessional staff are always reportingprofessional staff are always reportingsome things always change:some things always change:

requirementsrequirementsusersusers tools and platformstools and platformsbudgets …….budgets …….

version control is critically importantversion control is critically important

1717

Report aestheticsReport aesthetics

visual presentation stylevisual presentation style is it easy to look at?is it easy to look at?

writing stylewriting style is it easy to understand?is it easy to understand?

report structurereport structure is it easy to use?is it easy to use?

successful reports answer YES to allsuccessful reports answer YES to all

18

Specify the document

Draft and edit the document

Review the document

Publish the document

Maintain the document

Not OK

OK

The Documentation Process

1919

Specify the DocumentSpecify the Document

Conceptual decisionsConceptual decisions Break documentation down by taskBreak documentation down by task Use a minimalist designUse a minimalist design Develop a concept of audienceDevelop a concept of audience Identify the purpose for each documentIdentify the purpose for each document

Physical decisions:Physical decisions: Organise the documentationOrganise the documentation Choose appropriate mediaChoose appropriate media Decide on typography, layout, colour and page sizeDecide on typography, layout, colour and page size

Implementation decisions:Implementation decisions: Plan for updating, Develop a cost/time schedulePlan for updating, Develop a cost/time schedule

2020

Draft and Edit the DocumentDraft and Edit the Document

Overcome writer's blockOvercome writer's blockBe aware of how readers readBe aware of how readers readUse reader-based writing techniquesUse reader-based writing techniquesUse an appropriate document formatUse an appropriate document formatCreate your reference aidsCreate your reference aidsDevelop effective graphicsDevelop effective graphics

2121

Overcome Writer’s BlockOvercome Writer’s Block Internal writer's block Internal writer's block

Be prepared to write poorly and edit wellBe prepared to write poorly and edit well Don't feel you have to start at the beginning ... start where you feel Don't feel you have to start at the beginning ... start where you feel

most comfortablemost comfortable Tape what you want to tell them ... transcribe it and then editTape what you want to tell them ... transcribe it and then edit Stop in the middle of a section at the end of a day ... Stop in the middle of a section at the end of a day ...

makes it easier when you get back to itmakes it easier when you get back to it External writer's block External writer's block

Become an expert on the subject matterBecome 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 youOffer sources a variety of ways of getting information to you Use management leverageUse management leverage

2222

Review the DocumentReview the Document

Purpose - to let users try it out to see whether it is Purpose - to let users try it out to see whether it is effective and can stand aloneeffective 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 Coversheet - the users should know the duration of

the review, and how to return their comments to the the review, and how to return their comments to the authorsauthors

Feedback - let the users know how their comments Feedback - let the users know how their comments were used .. provide them with a summary reportwere used .. provide them with a summary report

2323

Publish the DocumentPublish the Document

Planning - make sure printers know the type of work Planning - make sure printers know the type of work you are giving them and are ready for ityou are giving them and are ready for it

Deadlines - leave plenty of time for this stage ... it Deadlines - leave plenty of time for this stage ... it can take up to 25% of the documentation effortcan take up to 25% of the documentation effort

Clarity -Clarity - the clearer your production instructions the clearer your production instructions the better your final productthe better your final product

2424

Maintain the DocumentMaintain the Document

Maintain a master copy of the document that Maintain a master copy of the document that notes all corrections and updated information;notes all corrections and updated information;

Date each correction and change and the reason Date each correction and change and the reason for it;for it;

Version control is important;Version control is important;Maintain a document distribution list ... make sure Maintain a document distribution list ... make sure

that the user acknowledges that they have that the user acknowledges that they have received the updates and have updated their received the updates and have updated their document.document.

2525

Updating is a fact of life.

All technical documents

must cater for updating

Hints on MaintenanceHints on Maintenance BindingBinding

large, updated often .. ring bindinglarge, updated often .. ring binding small .. easier just to reissuesmall .. easier just to reissue

Section numbering schemesSection 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 replacedwith 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 barsChange bars Reader comment sheetsReader comment sheets

Update checklists .. lists all areas of a document that need to be changed if any Update checklists .. lists all areas of a document that need to be changed if any one section changesone section changes

Author and production notes .. lists any special methods used in writing or Author and production notes .. lists any special methods used in writing or producing the documentproducing the document

2626

ReferencesReferences DWYER, J. (1997) The Business Communication Handbook (4DWYER, J. (1997) The Business Communication Handbook (4 thth edition) Prentice-Hall, New York, edition) Prentice-Hall, New York,

N.Y. N.Y.