1ict 421 it professional practice semester 1, 2005 project documentation diana adorno...
TRANSCRIPT
![Page 1: 1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno d.adorno@murdoch.edu.aud.adorno@murdoch.edu.au 0419 428 881](https://reader035.vdocuments.us/reader035/viewer/2022062801/56649e355503460f94b236c1/html5/thumbnails/1.jpg)
1 ICT 421 IT Professional Practice Semester 1, 2005
Project Documentation
Diana Adorno
[email protected] 0419 428 881
![Page 2: 1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno d.adorno@murdoch.edu.aud.adorno@murdoch.edu.au 0419 428 881](https://reader035.vdocuments.us/reader035/viewer/2022062801/56649e355503460f94b236c1/html5/thumbnails/2.jpg)
2 ICT 421 IT Professional Practice Semester 1, 2005
Overview
• What is the problem?
• What value do documents add?
• Strategies for getting the most out of the documentation effort.
• Getting the most out of your writing resource.
• Documentation plan
• Document design
![Page 3: 1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno d.adorno@murdoch.edu.aud.adorno@murdoch.edu.au 0419 428 881](https://reader035.vdocuments.us/reader035/viewer/2022062801/56649e355503460f94b236c1/html5/thumbnails/3.jpg)
3 ICT 421 IT Professional Practice Semester 1, 2005
What is the problem?
![Page 4: 1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno d.adorno@murdoch.edu.aud.adorno@murdoch.edu.au 0419 428 881](https://reader035.vdocuments.us/reader035/viewer/2022062801/56649e355503460f94b236c1/html5/thumbnails/4.jpg)
4 ICT 421 IT Professional Practice Semester 1, 2005
Reasons not to document
• Time-consuming
• Expensive
• Takes away from the “real” work
• Necessary evil
• Not necessary if system is designed well enough
Perceived disadvantages
![Page 5: 1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno d.adorno@murdoch.edu.aud.adorno@murdoch.edu.au 0419 428 881](https://reader035.vdocuments.us/reader035/viewer/2022062801/56649e355503460f94b236c1/html5/thumbnails/5.jpg)
5 ICT 421 IT Professional Practice Semester 1, 2005
What is a document?
• Tool to communicate
• Somewhere to store information or knowledge• As opposed to DNA, brain, hardware or
software
• Community product
Is a post-it note a document?Is a web page a document or software?
![Page 6: 1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno d.adorno@murdoch.edu.aud.adorno@murdoch.edu.au 0419 428 881](https://reader035.vdocuments.us/reader035/viewer/2022062801/56649e355503460f94b236c1/html5/thumbnails/6.jpg)
6 ICT 421 IT Professional Practice Semester 1, 2005
What is a document?
• Project documentation• Project plan, risk management plan...
• System documentation• Requirements, functional spec, System design, test
docs
• User documentation• Client (brief, Business requirements)• End-user (User guide, technical ref, online help)
• Post-it note & other informal documents
![Page 7: 1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno d.adorno@murdoch.edu.aud.adorno@murdoch.edu.au 0419 428 881](https://reader035.vdocuments.us/reader035/viewer/2022062801/56649e355503460f94b236c1/html5/thumbnails/7.jpg)
7 ICT 421 IT Professional Practice Semester 1, 2005
Document layers
Content
Container
Delivery method Audienc
e
![Page 8: 1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno d.adorno@murdoch.edu.aud.adorno@murdoch.edu.au 0419 428 881](https://reader035.vdocuments.us/reader035/viewer/2022062801/56649e355503460f94b236c1/html5/thumbnails/8.jpg)
8 ICT 421 IT Professional Practice Semester 1, 2005
Content delivery
Content • Online help• Error messages
Hard copy
Web page(HTML/ XML)
Online document (PDF)
![Page 9: 1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno d.adorno@murdoch.edu.aud.adorno@murdoch.edu.au 0419 428 881](https://reader035.vdocuments.us/reader035/viewer/2022062801/56649e355503460f94b236c1/html5/thumbnails/9.jpg)
9 ICT 421 IT Professional Practice Semester 1, 2005
A good document
• Short• Meets the expectations and needs of the
audience.• Supports the mission of the team• Consistent – presentation and language• Accurate• Usable• Complete• Verifiable
![Page 10: 1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno d.adorno@murdoch.edu.aud.adorno@murdoch.edu.au 0419 428 881](https://reader035.vdocuments.us/reader035/viewer/2022062801/56649e355503460f94b236c1/html5/thumbnails/10.jpg)
10 ICT 421 IT Professional Practice Semester 1, 2005
What value do documents add?
![Page 11: 1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno d.adorno@murdoch.edu.aud.adorno@murdoch.edu.au 0419 428 881](https://reader035.vdocuments.us/reader035/viewer/2022062801/56649e355503460f94b236c1/html5/thumbnails/11.jpg)
11 ICT 421 IT Professional Practice Semester 1, 2005
Value is relative
From http://www.lema.ulg.ac.be/LuciD/Course.htmlUniversity of Leige, Belgium, Lab of users cognition and intelligent design
![Page 12: 1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno d.adorno@murdoch.edu.aud.adorno@murdoch.edu.au 0419 428 881](https://reader035.vdocuments.us/reader035/viewer/2022062801/56649e355503460f94b236c1/html5/thumbnails/12.jpg)
12 ICT 421 IT Professional Practice Semester 1, 2005
Value of documentation
• Communication
• Legal
• Marketing and client relations
• Project management
• Design and development
• Knowledge management
What if there are no documents?
![Page 13: 1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno d.adorno@murdoch.edu.aud.adorno@murdoch.edu.au 0419 428 881](https://reader035.vdocuments.us/reader035/viewer/2022062801/56649e355503460f94b236c1/html5/thumbnails/13.jpg)
13 ICT 421 IT Professional Practice Semester 1, 2005
Communication
• Communication tool• to inform• convince• call to action• capture or specify• recommendation or proposal
• Conveys• Information• Image• Brand
![Page 14: 1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno d.adorno@murdoch.edu.aud.adorno@murdoch.edu.au 0419 428 881](https://reader035.vdocuments.us/reader035/viewer/2022062801/56649e355503460f94b236c1/html5/thumbnails/14.jpg)
14 ICT 421 IT Professional Practice Semester 1, 2005
Legal
• Contractual• Defense projects• Telecommunications• Compliance to industry standard for products
• Intellectual capital• Capture of design• Copyrights/ patents
![Page 15: 1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno d.adorno@murdoch.edu.aud.adorno@murdoch.edu.au 0419 428 881](https://reader035.vdocuments.us/reader035/viewer/2022062801/56649e355503460f94b236c1/html5/thumbnails/15.jpg)
15 ICT 421 IT Professional Practice Semester 1, 2005
Marketing and client relations
• Something to show without showing the system
• Conveys brand and impression of company
• Funding request (venture capital)
• Establish credibility with the client
• Buys time if delays
• Impression of a robust system
• Reinforce value of system Is it possible to have too much information?
![Page 16: 1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno d.adorno@murdoch.edu.aud.adorno@murdoch.edu.au 0419 428 881](https://reader035.vdocuments.us/reader035/viewer/2022062801/56649e355503460f94b236c1/html5/thumbnails/16.jpg)
16 ICT 421 IT Professional Practice Semester 1, 2005
Project Management
• Best use of gurus
• Milestones in plan
• Visibility (measure)
• Working as a team on single deliverable
• Buys tolerance• Project team• Management
• Reduces risk
![Page 17: 1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno d.adorno@murdoch.edu.aud.adorno@murdoch.edu.au 0419 428 881](https://reader035.vdocuments.us/reader035/viewer/2022062801/56649e355503460f94b236c1/html5/thumbnails/17.jpg)
17 ICT 421 IT Professional Practice Semester 1, 2005
Design & development
• Design before build
• Visible
• Maintenance
• Future developments
![Page 18: 1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno d.adorno@murdoch.edu.aud.adorno@murdoch.edu.au 0419 428 881](https://reader035.vdocuments.us/reader035/viewer/2022062801/56649e355503460f94b236c1/html5/thumbnails/18.jpg)
18 ICT 421 IT Professional Practice Semester 1, 2005
User manualProduct 3User manual
Product 2
Integration into development
Source text
Adobe Framemak
er
Error messages
Help text
Translators
User manualProduct 1
![Page 19: 1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno d.adorno@murdoch.edu.aud.adorno@murdoch.edu.au 0419 428 881](https://reader035.vdocuments.us/reader035/viewer/2022062801/56649e355503460f94b236c1/html5/thumbnails/19.jpg)
19 ICT 421 IT Professional Practice Semester 1, 2005
Approach
• Font• Screen or page (sans serif or serif)
• Use styles to separate introduction from how-to text.
• Online documentation• Use PDF
• Graphic designer required for cover
![Page 20: 1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno d.adorno@murdoch.edu.aud.adorno@murdoch.edu.au 0419 428 881](https://reader035.vdocuments.us/reader035/viewer/2022062801/56649e355503460f94b236c1/html5/thumbnails/20.jpg)
20 ICT 421 IT Professional Practice Semester 1, 2005
Knowledge capture
• Deliverables could be reused for future projects
• Passing on knowledge from one project phase to the next.
• Corporate knowledge and memory• Shortcuts and lessons learnt
![Page 21: 1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno d.adorno@murdoch.edu.aud.adorno@murdoch.edu.au 0419 428 881](https://reader035.vdocuments.us/reader035/viewer/2022062801/56649e355503460f94b236c1/html5/thumbnails/21.jpg)
21 ICT 421 IT Professional Practice Semester 1, 2005
Squeezing more out of documentation
• Do the minimum
• Research what audience needs• Only deliver what is useful
• Reuse effort wherever possible
• Reuse content
![Page 22: 1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno d.adorno@murdoch.edu.aud.adorno@murdoch.edu.au 0419 428 881](https://reader035.vdocuments.us/reader035/viewer/2022062801/56649e355503460f94b236c1/html5/thumbnails/22.jpg)
22 ICT 421 IT Professional Practice Semester 1, 2005
Levels of reuse
• Documents• Earlier projects, templates
• Components of documents• e.g. Copyright, Overview, Compliance matrix
• Effort• Design user manual to also cover help text
• The writing resource• Design, writing and testing
![Page 23: 1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno d.adorno@murdoch.edu.aud.adorno@murdoch.edu.au 0419 428 881](https://reader035.vdocuments.us/reader035/viewer/2022062801/56649e355503460f94b236c1/html5/thumbnails/23.jpg)
23 ICT 421 IT Professional Practice Semester 1, 2005
Reuse content
Requirementsanalysis
Decision analysis
Design analysis
Construction Implement-ation
Project Charter System Improveme
nt Objectives
BusinessRequiremen
tsStatement
System proposal
Design Specificatio
n
Test Specificatio
n
Project Plan
User Documentatio
n
Training course
material
Preliminary investigation& Problem analysis
Ops & support
Operations &Maintenance
Manual
![Page 24: 1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno d.adorno@murdoch.edu.aud.adorno@murdoch.edu.au 0419 428 881](https://reader035.vdocuments.us/reader035/viewer/2022062801/56649e355503460f94b236c1/html5/thumbnails/24.jpg)
24 ICT 421 IT Professional Practice Semester 1, 2005
Tools & Strategies
• Tools• Use what is already there.• Better use of current tools.• Know the tools you have, well.• Most issues are with the process, not the tools.
![Page 25: 1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno d.adorno@murdoch.edu.aud.adorno@murdoch.edu.au 0419 428 881](https://reader035.vdocuments.us/reader035/viewer/2022062801/56649e355503460f94b236c1/html5/thumbnails/25.jpg)
25 ICT 421 IT Professional Practice Semester 1, 2005
Approach
• Commit to doing documentation
• Research• Reuse templates and content• Know the audience well
• Methodology• Agree the approach before you start
![Page 26: 1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno d.adorno@murdoch.edu.aud.adorno@murdoch.edu.au 0419 428 881](https://reader035.vdocuments.us/reader035/viewer/2022062801/56649e355503460f94b236c1/html5/thumbnails/26.jpg)
26 ICT 421 IT Professional Practice Semester 1, 2005
Plan
• Write a document plan
• Choose the documents to write. Do only what is necessary, but do it well.
• Merge if possible
• Reuse where possible
• Use standards wherever possible
![Page 27: 1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno d.adorno@murdoch.edu.aud.adorno@murdoch.edu.au 0419 428 881](https://reader035.vdocuments.us/reader035/viewer/2022062801/56649e355503460f94b236c1/html5/thumbnails/27.jpg)
27 ICT 421 IT Professional Practice Semester 1, 2005
Standards
• Company style
• IEEE standards
• Industry standards
• Online communication standards• Joann Hackos
• Language & writing• Elements of Style, Strunk & White (1957)
![Page 28: 1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno d.adorno@murdoch.edu.aud.adorno@murdoch.edu.au 0419 428 881](https://reader035.vdocuments.us/reader035/viewer/2022062801/56649e355503460f94b236c1/html5/thumbnails/28.jpg)
28 ICT 421 IT Professional Practice Semester 1, 2005
Document Management
• Assign small components to people, not whole documents.
• Use text editors not word processors
• Design notes
• Capture the information as you go.
• Use a document manager
• Use an editor
• Use a graphic designer
![Page 29: 1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno d.adorno@murdoch.edu.aud.adorno@murdoch.edu.au 0419 428 881](https://reader035.vdocuments.us/reader035/viewer/2022062801/56649e355503460f94b236c1/html5/thumbnails/29.jpg)
29 ICT 421 IT Professional Practice Semester 1, 2005
Design & development
• Define the document structure early.
• Design well
• Consider document usability & accessibility
• Use a style guide
• Know the tools well
![Page 30: 1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno d.adorno@murdoch.edu.aud.adorno@murdoch.edu.au 0419 428 881](https://reader035.vdocuments.us/reader035/viewer/2022062801/56649e355503460f94b236c1/html5/thumbnails/30.jpg)
30 ICT 421 IT Professional Practice Semester 1, 2005
Test
• Test the document and test it early.
![Page 31: 1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno d.adorno@murdoch.edu.aud.adorno@murdoch.edu.au 0419 428 881](https://reader035.vdocuments.us/reader035/viewer/2022062801/56649e355503460f94b236c1/html5/thumbnails/31.jpg)
31 ICT 421 IT Professional Practice Semester 1, 2005
Reuse your writer
• Document writers are well placed to:• Edit project and system documents• Do early testing• Especially usability• Write the error messages• Suggest names for interface labels• Develop training• Train users
![Page 32: 1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno d.adorno@murdoch.edu.aud.adorno@murdoch.edu.au 0419 428 881](https://reader035.vdocuments.us/reader035/viewer/2022062801/56649e355503460f94b236c1/html5/thumbnails/32.jpg)
32 ICT 421 IT Professional Practice Semester 1, 2005
Document Plan
![Page 33: 1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno d.adorno@murdoch.edu.aud.adorno@murdoch.edu.au 0419 428 881](https://reader035.vdocuments.us/reader035/viewer/2022062801/56649e355503460f94b236c1/html5/thumbnails/33.jpg)
33 ICT 421 IT Professional Practice Semester 1, 2005
Draft table of contents
• Typically an appendix to the document.
• May be lengthy if there are several document deliverables to be produced.
• Include the the estimated number of pages for each section.
• What templates are already available
![Page 34: 1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno d.adorno@murdoch.edu.aud.adorno@murdoch.edu.au 0419 428 881](https://reader035.vdocuments.us/reader035/viewer/2022062801/56649e355503460f94b236c1/html5/thumbnails/34.jpg)
34 ICT 421 IT Professional Practice Semester 1, 2005
Typical generic structure
• Cover• Author/ Contributors• Approvals• Executive Summary• Table of Contents (and of figures, tables)• Introduction• Body sections• Conclusion/ Recommendation/ Summary• Glossary• Index
![Page 35: 1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno d.adorno@murdoch.edu.aud.adorno@murdoch.edu.au 0419 428 881](https://reader035.vdocuments.us/reader035/viewer/2022062801/56649e355503460f94b236c1/html5/thumbnails/35.jpg)
35 ICT 421 IT Professional Practice Semester 1, 2005
Example structure
• Executive summary 1 page
• Introduction 2 pages
• Section 1 5 pages
• Section 2 10 pages
• Glossary 2 pages
• Index 4 pages
• Total pages = 24 pages
![Page 36: 1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno d.adorno@murdoch.edu.aud.adorno@murdoch.edu.au 0419 428 881](https://reader035.vdocuments.us/reader035/viewer/2022062801/56649e355503460f94b236c1/html5/thumbnails/36.jpg)
36 ICT 421 IT Professional Practice Semester 1, 2005
Estimating the effort
• Estimate the number of pages.
• Calculate the amount of time per page.• Write• Edit• Review & update• Proofread• Publish
• Add a fixed period for research.
How long for 1 page?
![Page 37: 1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno d.adorno@murdoch.edu.aud.adorno@murdoch.edu.au 0419 428 881](https://reader035.vdocuments.us/reader035/viewer/2022062801/56649e355503460f94b236c1/html5/thumbnails/37.jpg)
37 ICT 421 IT Professional Practice Semester 1, 2005
Estimate effort
• Time per page: 5 hours• Write 2 hours• Edit 1 hour• Review 1 hour (allow for 2 reviews of 0.5)• Proofread 0.5 hour• Publish 0.5 hour
• 24 pages x 5 = 120 hours (15 days) • Add research time 10 days• Total = 15 + 10 = 25 days (5 weeks)
![Page 38: 1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno d.adorno@murdoch.edu.aud.adorno@murdoch.edu.au 0419 428 881](https://reader035.vdocuments.us/reader035/viewer/2022062801/56649e355503460f94b236c1/html5/thumbnails/38.jpg)
38 ICT 421 IT Professional Practice Semester 1, 2005
Document design
![Page 39: 1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno d.adorno@murdoch.edu.aud.adorno@murdoch.edu.au 0419 428 881](https://reader035.vdocuments.us/reader035/viewer/2022062801/56649e355503460f94b236c1/html5/thumbnails/39.jpg)
39 ICT 421 IT Professional Practice Semester 1, 2005
Parts of a document
• Page components
• Control components
• Content elements
• Page design elements
![Page 40: 1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno d.adorno@murdoch.edu.aud.adorno@murdoch.edu.au 0419 428 881](https://reader035.vdocuments.us/reader035/viewer/2022062801/56649e355503460f94b236c1/html5/thumbnails/40.jpg)
40 ICT 421 IT Professional Practice Semester 1, 2005
Page components
• Header
• Footer
• Gutter
• Margin
![Page 41: 1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno d.adorno@murdoch.edu.aud.adorno@murdoch.edu.au 0419 428 881](https://reader035.vdocuments.us/reader035/viewer/2022062801/56649e355503460f94b236c1/html5/thumbnails/41.jpg)
41 ICT 421 IT Professional Practice Semester 1, 2005
Control components
• Version number
• Name
• Author
• Document control
• Status
![Page 42: 1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno d.adorno@murdoch.edu.aud.adorno@murdoch.edu.au 0419 428 881](https://reader035.vdocuments.us/reader035/viewer/2022062801/56649e355503460f94b236c1/html5/thumbnails/42.jpg)
42 ICT 421 IT Professional Practice Semester 1, 2005
Content elements
• Heading 1, 2, 3, no-numbers
• Paragraph
• Bullet (levels 1, 2, 3)
• Numbered list (levels 1, 2, 3)
• Table Text
• Table Heading
• TOC 1, 2, 3
![Page 43: 1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno d.adorno@murdoch.edu.aud.adorno@murdoch.edu.au 0419 428 881](https://reader035.vdocuments.us/reader035/viewer/2022062801/56649e355503460f94b236c1/html5/thumbnails/43.jpg)
43 ICT 421 IT Professional Practice Semester 1, 2005
Page design elements
• White space• Margins, above headings, above text etc.
• Lines• Bullets• Lines (alignment)• Typeface (font)• Image• Colour• Shape• Movement