slide 1ict 327 management of it projectssemester 1, 2005 project documentation

ICT 327 Management of IT Projects Semester 1, 2005

Project documentation


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


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.


Outline

• What is a document?• Identify project documents• Why document?• Analysis• Planning your document

• Structure

• Designing your document• Layout

• Setting up your document• Writing


What is a document?

• Is a post-it note with an instruction a user guide?


Why document?

• Does a hair-dryer need a user manual?


Exercise

• List as many different project documents as you can


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


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?


Example scenario


Exercise

• Describe how to use a mobile phone to someone from Mars.


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


Document layers

Content

Container

Delivery method Audienc

e


Content delivery

Content • Online help• Error messages

Hard copy

Web page(HTML/ XML)

Online document (PDF)


User manualProduct 3User manual

Product 2

Integration into development

Source text

Adobe Framemak

er

Error messages

Help text

Translators

User manualProduct 1


Value of documentation


How to determine the value

• What if there are no documents?


Value is relative

From http://www.lema.ulg.ac.be/LuciD/Course.htmlUniversity of Leige, Belgium, Lab of users cognition and intelligent design

http://www.lema.ulg.ac.be/LuciD/Course.html


Value of documentation

• Communication

• Legal

• Marketing and client relations

• Project management

• Design and development

• Knowledge management


Communication

• Communication tool• to inform• convince• call to action• capture or specify• recommendation or proposal

• Conveys• Information• Image• Brand


Legal

• Contractual• Defense projects• Telecommunications• Compliance to industry standard for products

• Intellectual capital• Capture of design• Copyrights/ patents


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?


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


Design & development

• Design before build

• Visible

• Maintenance

• Future developments


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


Designing a document


Document Plan

• Project Document Plan• List all of the documents• Delivery – time and mechanism

• Individual Document Plan• Audience• Format• Structure (Chapter list)• Delivery mechanism


Layout

• Include examples – using same structural components

• Report

• Thesis

• User guide

• Marketing


Page Components

• Headings• Text• White space• Bullets• Lines• Images (Graphics, drawings)• Numbers• Tables (Table headings, Table text, Table bullets)


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)


Style detail Example

Heading 1: (Could be)• Arial,16pt, Bold, Left Justified

Heading 1• Garamond, 18pt, Bold, Italics, Centred


Style detail Example

Heading 1Text below the heading is usually body text. The space above is usually less than the space below. Each style must be calculated.

Heading 1Text below the heading is usually body text. The space above is usually less than the space below. Each style must be calculated.


Style guide

• Rules for usage

• Style usage

• Word usage


Navigational elements

• Table of contents

• Index

• Caption numbers

• Page numbers

• Headings


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)


Structure

• Depends on the complexity of the system

• E.g. A standard landline phone

• Purpose


Creating an index

• Why do it?

• Examples: White pages and Yellow pages

• Relates to search engine building, information architecture

Broad term

Narrow term Narrow term


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


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


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


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


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


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?


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)


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


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


The process: Similar to producing any system

• Plan• Analysis

• Identify the users• Identify their needs• Identify the features

(content) to meet their needs.

• Design• High-level structure• Detailed: Content

• Build• Write

• Test• Edit• Proof-read

• Implement• Publish


Document production tips


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)


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


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


Set up your own shortcuts

• Format> Style

• Click Modify

• Click Shortcut

• Tip: Use Combination keys for your shortcuts. E.g. Ctrl + Alt + R


Print your short cuts

1. File> Print

2. In the ‘Print What’ list: choose ‘Key Assignments’

2


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

Automatically picks up Heading styles 1,2 and 3

Automatically picks iup Caption style

slide 1ict 327 management of it projectssemester 1, 2005 project documentation

Documents

project documentation

document writing slide

value of documentation

documentation plan slide

example scenario slide

project of user document

document content

document layout