1ICT 421 IT Professional Practice Semester 1, 2005 Project Documentation Diana Adorno

2ICT 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

3ICT 421 IT Professional Practice Semester 1, 2005 What is the problem?

4ICT 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

5ICT 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?

6ICT 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

7ICT 421 IT Professional Practice Semester 1, 2005 Document layers Content Container Delivery method Audience

8ICT 421 IT Professional Practice Semester 1, 2005 Content delivery Content Online help Error messages Hard copy Web page (HTML/ XML) Online document (PDF)

9ICT 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

10ICT 421 IT Professional Practice Semester 1, 2005 What value do documents add?

11ICT 421 IT Professional Practice Semester 1, 2005 Value is relative From University of Leige, Belgium, Lab of users cognition and intelligent design

12ICT 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?

13ICT 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

14ICT 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

15ICT 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?

16ICT 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

17ICT 421 IT Professional Practice Semester 1, 2005 Design & development Design before build Visible Maintenance Future developments

18ICT 421 IT Professional Practice Semester 1, 2005 User manual Product 3 User manual Product 2 Integration into development Source text Adobe Framemaker Error messages Help text Translators User manual Product 1

19ICT 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

20ICT 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

21ICT 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

22ICT 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

23ICT 421 IT Professional Practice Semester 1, 2005 Reuse content Requirements analysis Decision analysis Design analysis ConstructionImplement -ation Project Charter System Improvement Objectives Business Requirements Statement System proposal Design Specification Test Specification Project Plan User Documentation Training course material Preliminary investigation & Problem analysis Ops & support Operations & Maintenance Manual

24ICT 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.

25ICT 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

26ICT 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

27ICT 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)

28ICT 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

29ICT 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

30ICT 421 IT Professional Practice Semester 1, 2005 Test Test the document and test it early.

31ICT 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

32ICT 421 IT Professional Practice Semester 1, 2005 Document Plan

33ICT 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

34ICT 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

35ICT 421 IT Professional Practice Semester 1, 2005 Example structure Executive summary 1 page Introduction2 pages Section 15 pages Section 210 pages Glossary2 pages Index4 pages Total pages = 24 pages

36ICT 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?

37ICT 421 IT Professional Practice Semester 1, 2005 Estimate effort Time per page: 5 hours Write2 hours Edit1 hour Review1 hour (allow for 2 reviews of 0.5) Proofread0.5 hour Publish0.5 hour 24 pages x 5 = 120 hours (15 days) Add research time 10 days Total = = 25 days (5 weeks)

38ICT 421 IT Professional Practice Semester 1, 2005 Document design

39ICT 421 IT Professional Practice Semester 1, 2005 Parts of a document Page components Control components Content elements Page design elements

40ICT 421 IT Professional Practice Semester 1, 2005 Page components Header Footer Gutter Margin

41ICT 421 IT Professional Practice Semester 1, 2005 Control components Version number Name Author Document control Status

42ICT 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

43ICT 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