1. Slide 1ICT 327 Management of IT ProjectsSemester 1, 2005 Project documentation

2. Slide 2ICT 327 Management of IT ProjectsSemester 1, 2005 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

3. Slide 3ICT 327 Management of IT ProjectsSemester 1, 2005 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.

4. Slide 4ICT 327 Management of IT ProjectsSemester 1, 2005 Outline What is a document? Identify project documents Why document? Analysis Planning your document Structure Designing your document Layout Setting up your document Writing

5. Slide 5ICT 327 Management of IT ProjectsSemester 1, 2005 What is a document? Is a post-it note with an instruction a user guide?

6. Slide 6ICT 327 Management of IT ProjectsSemester 1, 2005 Why document? Does a hair-dryer need a user manual?

7. Slide 7ICT 327 Management of IT ProjectsSemester 1, 2005 Exercise List as many different project documents as you can

8. Slide 8ICT 327 Management of IT ProjectsSemester 1, 2005 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

9. Slide 9ICT 327 Management of IT ProjectsSemester 1, 2005 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?

10. Slide 10ICT 327 Management of IT ProjectsSemester 1, 2005 Example scenario

11. Slide 11ICT 327 Management of IT ProjectsSemester 1, 2005 Exercise Describe how to use a mobile phone to someone from Mars.

12. Slide 12ICT 327 Management of IT ProjectsSemester 1, 2005 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

13. Slide 13ICT 327 Management of IT ProjectsSemester 1, 2005 Document layers Content Container Delivery method Audience

14. Slide 14ICT 327 Management of IT ProjectsSemester 1, 2005 Content delivery Content Online help Error messages Hard copy Web page (HTML/ XML) Online document (PDF)

15. Slide 15ICT 327 Management of IT ProjectsSemester 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

16. Slide 16ICT 327 Management of IT ProjectsSemester 1, 2005 Value of documentation

17. Slide 17ICT 327 Management of IT ProjectsSemester 1, 2005 How to determine the value What if there are no documents?

18. Slide 18ICT 327 Management of IT ProjectsSemester 1, 2005 Value is relative From http://www.lema.ulg.ac.be/LuciD/Course.htmlhttp://www.lema.ulg.ac.be/LuciD/Course.html University of Leige, Belgium, Lab of users cognition and intelligent design

19. Slide 19ICT 327 Management of IT ProjectsSemester 1, 2005 Value of documentation Communication Legal Marketing and client relations Project management Design and development Knowledge management

20. Slide 20ICT 327 Management of IT ProjectsSemester 1, 2005 Communication Communication tool to inform convince call to action capture or specify recommendation or proposal Conveys Information Image Brand

21. Slide 21ICT 327 Management of IT ProjectsSemester 1, 2005 Legal Contractual Defense projects Telecommunications Compliance to industry standard for products Intellectual capital Capture of design Copyrights/ patents

22. Slide 22ICT 327 Management of IT ProjectsSemester 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?

23. Slide 23ICT 327 Management of IT ProjectsSemester 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

24. Slide 24ICT 327 Management of IT ProjectsSemester 1, 2005 Design & development Design before build Visible Maintenance Future developments

25. Slide 25ICT 327 Management of IT ProjectsSemester 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

26. Slide 26ICT 327 Management of IT ProjectsSemester 1, 2005 Designing a document

27. Slide 27ICT 327 Management of IT ProjectsSemester 1, 2005 Document Plan Project Document Plan List all of the documents Delivery – time and mechanism Individual Document Plan Audience Format Structure (Chapter list) Delivery mechanism

28. Slide 28ICT 327 Management of IT ProjectsSemester 1, 2005 Layout Include examples – using same structural components Report Thesis User guide Marketing

29. Slide 29ICT 327 Management of IT ProjectsSemester 1, 2005 Page Components Headings Text White space Bullets Lines Images (Graphics, drawings) Numbers Tables (Table headings, Table text, Table bullets)

30. Slide 30ICT 327 Management of IT ProjectsSemester 1, 2005 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)

31. Slide 31ICT 327 Management of IT ProjectsSemester 1, 2005 Style detail Example Heading 1: (Could be) Arial,16pt, Bold, Left Justified Heading 1 Garamond, 18pt, Bold, Italics, Centred

32. Slide 32ICT 327 Management of IT ProjectsSemester 1, 2005 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.

33. Slide 33ICT 327 Management of IT ProjectsSemester 1, 2005 Style guide Rules for usage Style usage Word usage

34. Slide 34ICT 327 Management of IT ProjectsSemester 1, 2005 Navigational elements Table of contents Index Caption numbers Page numbers Headings

35. Slide 35ICT 327 Management of IT ProjectsSemester 1, 2005 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)

36. Slide 36ICT 327 Management of IT ProjectsSemester 1, 2005 Structure Depends on the complexity of the system E.g. A standard landline phone Purpose

37. Slide 37ICT 327 Management of IT ProjectsSemester 1, 2005 Creating an index Why do it? Examples: White pages and Yellow pages Relates to search engine building, information architecture Broad term Narrow term

38. Slide 38ICT 327 Management of IT ProjectsSemester 1, 2005 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

39. Slide 39ICT 327 Management of IT ProjectsSemester 1, 2005 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

40. Slide 40ICT 327 Management of IT ProjectsSemester 1, 2005 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

41. Slide 41ICT 327 Management of IT ProjectsSemester 1, 2005 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

42. Slide 42ICT 327 Management of IT ProjectsSemester 1, 2005 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

43. Slide 43ICT 327 Management of IT ProjectsSemester 1, 2005 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?

44. Slide 44ICT 327 Management of IT ProjectsSemester 1, 2005 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)

45. Slide 45ICT 327 Management of IT ProjectsSemester 1, 2005 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

46. Slide 46ICT 327 Management of IT ProjectsSemester 1, 2005 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

47. Slide 47ICT 327 Management of IT ProjectsSemester 1, 2005 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

48. Slide 48ICT 327 Management of IT ProjectsSemester 1, 2005 Document production tips

49. Slide 49ICT 327 Management of IT ProjectsSemester 1, 2005 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)

50. Slide 50ICT 327 Management of IT ProjectsSemester 1, 2005 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

51. Slide 51ICT 327 Management of IT ProjectsSemester 1, 2005 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

52. Slide 52ICT 327 Management of IT ProjectsSemester 1, 2005 Set up your own shortcuts Format> Style Click Modify Click Shortcut Tip: Use Combination keys for your shortcuts. E.g. Ctrl + Alt + R

53. Slide 53ICT 327 Management of IT ProjectsSemester 1, 2005 Print your short cuts 1.File> Print 2.In the ‘Print What’ list: choose ‘Key Assignments’ 2

54. Slide 54ICT 327 Management of IT ProjectsSemester 1, 2005 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