Survey
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this 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