1ict 421 it professional practice semester 1, 2005 project documentation diana adorno...

1 ICT 421 IT Professional Practice Semester 1, 2005

Project Documentation

Diana Adorno

[email protected] 0419 428 881

mailto:[email protected]


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


What is the problem?


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


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?


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


Document layers

Content

Container

Delivery method Audienc

e


Content delivery

Content • Online help• Error messages

Hard copy

Web page(HTML/ XML)

Online document (PDF)


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


What value do documents add?


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

What if there are no documents?


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


User manualProduct 3User manual

Product 2

Integration into development

Source text

Adobe Framemak

er

Error messages

Help text

Translators

User manualProduct 1


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


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


Squeezing more out of documentation

• Do the minimum

• Research what audience needs• Only deliver what is useful

• Reuse effort wherever possible

• Reuse content


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


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


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.


Approach

• Commit to doing documentation

• Research• Reuse templates and content• Know the audience well

• Methodology• Agree the approach before you start


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


Standards

• Company style

• IEEE standards

• Industry standards

• Online communication standards• Joann Hackos

• Language & writing• Elements of Style, Strunk & White (1957)


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


Design & development

• Define the document structure early.

• Design well

• Consider document usability & accessibility

• Use a style guide

• Know the tools well


Test

• Test the document and test it early.


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


Document Plan


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


Typical generic structure

• Cover• Author/ Contributors• Approvals• Executive Summary• Table of Contents (and of figures, tables)• Introduction• Body sections• Conclusion/ Recommendation/ Summary• Glossary• Index


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


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?


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)


Document design


Parts of a document

• Page components

• Control components

• Content elements

• Page design elements


Page components

• Header

• Footer

• Gutter

• Margin


Control components

• Version number

• Name

• Author

• Document control

• Status


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 design elements

• White space• Margins, above headings, above text etc.

• Lines• Bullets• Lines (alignment)• Typeface (font)• Image• Colour• Shape• Movement