Download ICT 327 Topic 11 2005 Semester 1 (Project

Project documentation
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 1
Learning Objectives
• Be able to define what is and what is not a
document.
• Identify the difference between the
document content, its container and
delivery method.
• Explain with examples the importance of
documentation
• Explain the value of a documentation plan
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 2
Learning Objectives
• List the value of documentation to a project.
• List different types of documents used on a
project.
• List reasons to document.
• Be able to justify creating a project of user
document.
• List the different types of project
documentation.
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 3
Outline
•
•
•
•
•
What is a document?
Identify project documents
Why document?
Analysis
Planning your document
• Structure
• Designing your document
• Layout
• Setting up your document
• Writing
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 4
What is a document?
• Is a post-it note with an instruction a user
guide?
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 5
Why document?
• Does a hair-dryer need a user manual?
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 6
Exercise
• List as many different project documents as
you can
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 7
Project Documents
• Project documentation
• Project plan, schedule risk management plan,
minutes...
• 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
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 8
Who it is for?
•
•
•
•
Who are the people who will use it?
What do they want?
How will they use it?
What is the physical
environment the
manual will be used in?
• What do they already
know?
• What do they need
know?
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 9
Example scenario
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 10
Exercise
• Describe how to use a mobile phone to
someone from Mars.
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 11
A good document is…
• Short (unless it needs to be long)
• Meets the expectations and needs of the
audience.
• Supports the mission of the team
• Consistent – presentation and language
• Accurate
• Usable
• Complete
• Verifiable
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 12
Document layers
Content
Container
Delivery
method
ICT 327 Management of IT Projects
Audience
Semester 1, 2005
Slide 13
Content delivery
Hard copy
Web page
(HTML/ XML)
Content
• Online help
• Error messages
Online document (PDF)
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 14
Integration into development
Error messages
Source text
Adobe
Framemaker
User manual
manual
User User
manual
Product 3
Product
Product 1 2
Help text
Translators
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 15
Value of documentation
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 16
How to determine the value
• What if there are no documents?
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 17
Value is relative
From http://www.lema.ulg.ac.be/LuciD/Course.html
University of Leige, Belgium, Lab of users cognition and intelligent design
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 18
Value of documentation
•
•
•
•
•
•
Communication
Legal
Marketing and client relations
Project management
Design and development
Knowledge management
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 19
Communication
• Communication tool
•
•
•
•
•
to inform
convince
call to action
capture or specify
recommendation or proposal
• Conveys
• Information
• Image
• Brand
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 20
Legal
• Contractual
• Defense projects
• Telecommunications
• Compliance to industry standard for products
• Intellectual capital
• Capture of design
• Copyrights/ patents
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 21
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
Is it possible to have
• Reinforce value of system
too much information?
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 22
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
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 23
Design & development
•
•
•
•
Design before build
Visible
Maintenance
Future developments
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 24
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
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 25
Designing a document
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 26
Document Plan
• Project Document Plan
• List all of the documents
• Delivery – time and mechanism
• Individual Document Plan
•
•
•
•
Audience
Format
Structure (Chapter list)
Delivery mechanism
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 27
Layout
• Include examples – using same structural
components
• Report
• Thesis
• User guide
• Marketing
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 28
Page Components
•
•
•
•
•
•
•
•
Headings
Text
White space
Bullets
Lines
Images (Graphics, drawings)
Numbers
Tables (Table headings, Table text, Table bullets)
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 29
In Word
•
•
•
•
•
•
•
These map to Styles
Headings > Heading 1, Heading 2, Heading 3
Text > Body Text
Bullets > List Bullet 1, List Bullet 2, List Bullet 3
Lines
White space
Images (Graphics, drawings) – Image (followed
by Caption)
• Numbers
• Tables (Table headings, Table text, Table bullets)
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 30
Style detail Example
Heading 1: (Could be)
• Arial,16pt, Bold, Left Justified
Heading 1
• Garamond, 18pt, Bold, Italics, Centred
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 31
Style detail Example
Heading 1
Text below the heading is usually body text.
The space above is usually less than the space
below. Each style must be calculated.
Heading 1
Text below the heading is usually body text.
The space above is usually less than the space
below. Each style must be calculated.
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 32
Style guide
• Rules for usage
• Style usage
• Word usage
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 33
Navigational elements
•
•
•
•
•
Table of contents
Index
Caption numbers
Page numbers
Headings
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 34
Navigation on a single page
•
•
•
•
Title/ headings
Subheadings
Numbering on headings (if any)
Spacing (may give a clue to the type of
page)
• Page number
• Header and footer (control features & nav
features (field-Heading 1)
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 35
Structure
• Depends on the complexity of the system
• E.g. A standard landline phone
• Purpose
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 36
Creating an index
• Why do it?
• Examples: White pages and Yellow pages
• Relates to search engine building,
information architecture
Broad term
Narrow term
ICT 327 Management of IT Projects
Narrow term
Semester 1, 2005
Slide 37
Example
• Writing a recipe book
• Babganoush
• File under:
•
•
•
•
•
•
•
•
•
B - Babaganoush
F – Father’s favourite, Babaganoush
D = Dips, Babaganoush
A – Appetiser, Babaganoush
S = Starter, Babaganoush
E – Eggplant (or A – Aubergine), Babaganoush
S – Summer food, Babaganoush
L – Light food, Babaganoush
V – Vegetarian, Babaganoush
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 38
Controlling an entry
• Where are the main entries?
• See and See also
•
•
•
•
•
•
•
•
•
B – Babaganoush, p 8
F – Father’s favourite, See Babaganoush
D – Dips, See Babaganoush
A – Appetiser, See Babaganoush
S – Starter, See Babaganoush
E – Eggplant (or A – Aubergine), See Babaganoush
S – Summer food, See Babaganoush
L – Light food, See Babaganoush
V – Vegetarian, See Babaganoush
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 39
Relate entries
• See also
• See and See also
• B – Babaganoush, p 8
• See also, Dips
• F – Father’s favourite, See Babaganoush
• See also, Dips
• D – Dips, See Babaganoush
• A – Appetiser, See Babaganoush
• S – Starter, See Babaganoush
• See also, Dips
•
•
•
•
E – Eggplant (or A – Aubergine), See Babaganoush
S – Summer food, See Babaganoush
L – Light food, See Babaganoush
V – Vegetarian See Babaganoush
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 40
Exercise
• Take a single line in your mobile document
and create an index entry.
• In pairs, brainstorm possible terms that
could go into your index
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 41
Structure of the writing
•
•
•
•
Purpose
What it can be used for
Benefits (maybe)
Instructions for the different features
• How to make a call
• How to send text message
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 42
Writing a user guide
• Who is it for?
• Personas
• How are they going to use it?
• Navigational/ structural design (User guide,
tech ref manual)
• What format is appropriate?
• What are some possible scenarios?
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 43
Types of user documents
• User Manuals
• (End) User Guide
• Introduction
• Grouped by feature area (starting simplex and increasing in
complexity)
• Technical Reference Manual
•
•
•
•
•
Overview of system
Prior knowledge required
System Context (Related systems)
System overview
Chapters by feature, function or component (often
alphabetically)
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 44
User manual
• About this manual
• Who should read this manual
• Introduction
• Parts of the system
• Getting started
• What you can see
• How to start up (& shut-down)
• First function
• – e.g. Opening a document, making a call
• Index, TOC, TOF, TOT, TO?, Glossary
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 45
Consider
• Including:
•
•
•
•
•
Trouble-shooting guide
List of error messages
Tips, tricks and notes
Glossary with page number references
Bibliography (referenced documents)
• How your layout helps the readability
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 46
The process: Similar to producing any system
• Plan
• Analysis
• Build
• Write
• Identify the users
• Identify their needs
• Identify the features
(content) to meet their
needs.
• Design
• Test
• Edit
• Proof-read
• Implement
• Publish
• High-level structure
• Detailed: Content
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 47
Document production tips
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 48
Drawing tips
• Captions
• Insert> caption
• Choose label
• Type text
• Drawing
•
•
•
•
Constrain lines (using Shift key)
Align elements
Evenly distribute elements
Nudge (turn ‘snap to grid’ off for micro nudging)
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 49
Table tips
• Set up styles
•
•
•
•
Table Heading (Bold, 3pts above and below)
Table Text (2 pts above and below)
Table Bullet
Table List
• Layout
• Consider a sans serif font
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 50
Word shortcuts
• Full list – Help> Type Shortcuts
•
•
•
•
•
•
•
•
•
Heading 1 – Ctrl + Alt + 1
Heading 2 – Ctrl + Alt + 2
Heading 3 – Ctrl + Alt + 3
F3 – Cycle through capitalisation
Shift + F5 – Previous place edited in document
Top & End of document - Ctrl + Home, Ctrl + End
Next paragraph – Ctrl + 
F9 – Update field
Shift + F9 – Toggle field on/off
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 51
Set up your own shortcuts
• Format> Style
• Click Modify
• Click Shortcut
• Tip: Use Combination keys for your
shortcuts. E.g. Ctrl + Alt + R
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 52
Print your short cuts
1. File> Print
2. In the ‘Print
What’ list:
choose ‘Key
Assignments’
2
ICT 327 Management of IT Projects
Semester 1, 2005
Slide 53
Table of Contents, Figures, Tables
Table of Contents
• Insert> Index and Tables
• Choose Table of Contents
• Choose Options
• Set Heading 1 to 1
• Set Heading 2 to 2
• Set all others off
Table of Figures/ Tables
• Insert> Index and Tables
• Choose Table of Figures or Tables
ICT 327 Management of IT Projects
Semester 1, 2005
Automatically
picks up Heading
styles 1,2 and 3
Automatically
picks iup Caption
style
Slide 54