cse1204 - information systems 1 communication and documentation: additional notes on written reports
Post on 21-Dec-2015
219 views
TRANSCRIPT
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.