Document Development Cycle TECO 63 M. Reber 1_05 1/6/2005 TECO 63 De Anza College

01/06/2005 TECO 63 De Anza College

Table of Contents The Document Assignment Proposal Functional Specifications Blueprint Drafts Reviews Final User Guide 01/06/2005 TECO 63 De Anza College

The Document Assignment The culminating product of the assignment is a 30-35 page camera-ready, portfolio-quality user’s guide Research, analyze, plan, schedule, design, write, and evaluate a 30-35 page manual You function in two capacities in the creation of user’s guide, as a content expert and as a writer You select a topic you are an expert on and the topic will be assigned to a writer in the class who, with your help, will create a guide on your topic As a writer, you are assigned a topic you are unfamiliar with and a content expert to help you create a user’s guide 01/06/2005 TECO 63 De Anza College

Functional Specification Deliverables Functional Specification Proposal Blue Print Draft – 1 Reviewed by Content Expert Draft – 2 Content Expert & Peer Final User Guide Draft - 3 Instructor 01/06/2005 TECO 63 De Anza College

Proposal 1/6/2005 TECO 63 De Anza College

Proposal Definition and Scope Proposal is the document where you specify your content area of expertise and state the end objectives, audience profile, and the key tasks that you will explore in the manual You write a brief proposal providing explanation of the topic you propose to be content expert on to ensure that the topic is of appropriate complexity 01/06/2005 TECO 63 De Anza College

Proposal Template Title of proposal Statement of proposal Give a short title of your proposal Statement of proposal State in 2-4 sentences the subject you propose to be a content expert for Define the scope of your proposal indicating what parts of the process you will cover and what parts fall beyond the scope of the guide Explain in detail you familiarity with the subject and how you have gained your expertise in this area 01/06/2005 TECO 63 De Anza College

Proposal Template (Cont.) Processes involved Identify at least 5 separate tasks that are required for your subject Definition of Main Concepts and Terms Ensure your topic is sufficiently complex Identify at least 8 key terms or concepts not obvious to the average reader that would need to be explained regarding your project Troubleshooting Describe any common problems that occur with your topic and how they are resolved 01/06/2005 TECO 63 De Anza College

Sample Proposal 01/06/2005 TECO 63 De Anza College

Functional Specification 1/6/2005 TECO 63 De Anza College

Functional Specification Definition and Scope As a content expert, you will: create a functional specification to give a clear understanding of your subject matter explain in detail all that you know about your subject 01/06/2005 TECO 63 De Anza College

Functional Specification Template Purpose State in 1-2 sentences the purpose of the user guide Scope State clearly what the guide will cover and what it will not cover Prerequisites/Requirements Identify who the audience for the guide is and their prior knowledge on the subject State the expected knowledge and experience assumed, if you are writing for an advanced learner profile List any tools or supplies that will be required for an individual to complete the tasks outlined in the guide 01/06/2005 TECO 63 De Anza College

Functional Specification Template (Cont.) Processes Identify what separate processes will need to be covered in the guide to maintain sufficient complexity Must have a minimum of 4 separate processes, each with distinct steps Troubleshooting Anticipate common problems a user may encounter that will need to be addressed Glossary List and define key terms that will be used and are essential for accomplishing the purpose 01/06/2005 TECO 63 De Anza College

Sample Functional Specification 01/06/2005 TECO 63 De Anza College

Blueprint 1/6/2005 TECO 63 De Anza College

Blueprint Definition and Scope Blueprint serves as the fundamental structure of the document You create a blueprint that outlines the entire structure of your guide, including heading at every level with a brief explanation of the topic 01/06/2005 TECO 63 De Anza College

Blueprint Template Identify the people who will be involved as a writer, a content expert, and as a peer reviewer Identify the timeline associated with each activity till project completion Maintain parallelism in the headings Start each heading with a verb Combine headings wherever appropriate and avoid too many headings Do not have Level 1 heading without a Level 2 heading Do not have Level 1 heading with only a single Level 2 heading Explain briefly what will be covered in each section and do not write the entire content Follow the Blueprint format 01/06/2005 TECO 63 De Anza College

Sample Blueprint 01/06/2005 TECO 63 De Anza College

Drafts 1/6/2005 TECO 63 De Anza College

Draft - 1 Definition and Scope You will create three drafts during the documentation process For the first draft: Ensure your document contains all the details and other related explanations and the information presented is technically accurate (Macro level) Ensure comprehensiveness of the document, a step towards a complete guide with all sections and steps written Ensure the basic formatting elements are in place 01/06/2005 TECO 63 De Anza College

Sample Draft - 1 01/06/2005 TECO 63 De Anza College

Draft – 2 Scope Ensure: the technical information is accurate at the micro level the document is reader-focused (usability) the format is finalized 01/06/2005 TECO 63 De Anza College

Sample Draft - 2 01/06/2005 TECO 63 De Anza College

Draft – 3 Scope Ensure the manual: contains all the relevant graphics is perfect in all aspects by your estimation Is of camera-ready quality Create a mock-up version of the manual including print, binding, cover, and over-all presentation 01/06/2005 TECO 63 De Anza College

Sample Draft - 3 01/06/2005 TECO 63 De Anza College

Reviews 1/6/2005 TECO 63 De Anza College

Content Expert Review As a content expert, you will review the each draft created by the writer assigned to your topic You will ensure technical accuracy of the content and improve the overall usability of the document You will be graded by the quality of the comments that you make to your writer Use the User Guide Style Guide checklist for review 01/06/2005 TECO 63 De Anza College

Tips for Content Expert Review Look for: Technical accuracy of content Adequacy of the technical content Whether the content meets the objective of the topic End-user pre-requisite knowledge and difficulty level in performing the tasks 01/06/2005 TECO 63 De Anza College

Peer Review You will review the guide of another classmate in addition to the guide you review as a content expert You will function as a potential user by conducting a usability test As a target audience, you will provide valuable feedback to the writer to help communicate effectively You will be graded on the quality of the comments you make to the guide Use the User Guide Style Guide checklist for review 01/06/2005 TECO 63 De Anza College

Tips for Peer Review Look for: Parallelism in headings Adequate white spaces Consistent formatting Run-on / incomplete sentences Active voice Correct punctuation marks Grammatically incorrect sentences, such as subject-verb match End-user focused Adequacy of technical content Clarity of tasks 01/06/2005 TECO 63 De Anza College

Final User Guide 1/6/2005 TECO 63 De Anza College

Final User Guide The USER’S GUIDE, due at Final The guide will be graded on: Overall usability Style Presentation Graphics Accuracy Fit to audience Correct application of format, grammar, and punctuation 01/06/2005 TECO 63 De Anza College