1 / 36

Document Development Cycle

Document Development Cycle. Creating Your User’s Guide Step-by-Step. Overview. The Document Assignment Flowchart of the Deliverables Proposal Functional Specifications Blueprint Drafts Reviews Final User Guide. Overview. The Document Assignment Flowchart of the Deliverables

adsila
Download Presentation

Document Development Cycle

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript

  1. Document Development Cycle Creating Your User’s Guide Step-by-Step

  2. Overview • The Document Assignment • Flowchart of the Deliverables • Proposal • Functional Specifications • Blueprint • Drafts • Reviews • Final User Guide

  3. Overview • The Document Assignment • Flowchart of the Deliverables • Proposal • Functional Specifications • Blueprint • Drafts • Reviews • Final User Guide

  4. The Document Assignment • The culminating product of the assignment is a 35-50 page camera-ready, portfolio-quality user’s guide • Research, analyze, plan, schedule, design, write, and evaluate a 35-50 page manual • You function in two capacities in the creation of user’s guides: • Content Expert. Select a topic you are an “expert” on and this topic will be assigned to a writer in the class • Writer. You are assigned a topic you are unfamiliar with and a content expert to help you create a guide

  5. Overview • The Document Assignment • Flowchart of the Deliverables • Proposal • Functional Specifications • Blueprint • Drafts • Reviews • Final User Guide

  6. Proposal Functional Specification Blue Print Draft – 1 Reviewed by Content Expert Draft – 2 Reviewed by Content Expert & Peer Draft - 3 Reviewed by Instructor Final User Guide Flowchart of the Deliverables

  7. Overview • The Document Assignment • Flowchart of the Deliverables • Proposal • Functional Specifications • Blueprint • Drafts • Reviews • Final User Guide

  8. Proposal Definition and Scope • In the proposal you: • Specify your content area of expertise and the scope • Identify the end objectives, audience profile, and key tasks • The proposal ensures: • You know your topic • The topic is of appropriate depth and complexity • Do not be intimidated by the page count • Focus on the content and the assignment requirements • The page count is impossible to predict and is wildly inflated by graphics, TOC, Index, etc.

  9. Proposal Template • Title 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 your familiarity with the subject and how you have gained your expertise in this area

  10. Proposal Template (cont.) • Processes involved • Identify at least 5 separate tasks that are required for your subject (each task must have 3 or more steps) • 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

  11. Sample Proposal

  12. Overview • The Document Assignment • Flowchart of the Deliverables • Proposal • Functional Specifications • Blueprint • Drafts • Reviews • Final User Guide

  13. Functional Specification Definition and Scope • As a content expert, you: • Create a functional specification to give a clear understanding of your subject matter • Explain in detail all that you know about your subject • Provide the writer with an “organized brain dump” to get them started • This functional specification allows the writer to start learning about their new subject matter • It forms the basis of subsequent conversations and informational interviewing

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

  15. 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 5 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

  16. Sample Functional Specification

  17. Overview • The Document Assignment • Flowchart of the Deliverables • Proposal • Functional Specifications • Blueprint • Drafts • Reviews • Final User Guide

  18. Blueprint Definition and Scope • The blueprint outlines the structure of the user’s guide you plan to write • It details every section of your guide. It includes: • Every heading of every section at every level • A brief description of the information that will be documented in each section (not the information itself) • The structure of your guide may change as you begin drafting, but designing a blueprint helps you develop a solid initial plan • You can diverge from your blueprint as you become more familiar with your subject • You do NOT need to go back and revise the blueprint

  19. Blueprint Template • Follow the Blueprint format • Be sure to: • 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 until project completion • Maintain parallelism in the headings • Find the best balance of headings with text • Too many headings will fragment your content and disrupt flow • Too few headings will make it difficult to access information • Do not have an H1 without an H2 • Do not have an H1 with only a single H2 (applies to subsequent levels) • Explain briefly what will be covered in each section but do not write the actual content

  20. Sample Blueprint

  21. Overview • The Document Assignment • Flowchart of the Deliverables • Proposal • Functional Specifications • Blueprint • Drafts • Reviews • Final User Guide

  22. Draft 1: Expectations • You will create three drafts during the documentation process • For the first draft: • Ensure your document contains all the content • Ensure you document is technically accurate at the macro level • Ensure comprehensiveness of the guide by defining all terms, writing all steps, and giving all explanations • Ensure the basic formatting elements are in place • Most students find it is easier to set the design early • You should focus on content over design, however, at this stage • This draft will be reviewed by your content expert

  23. Sample Draft 1

  24. Draft 2: Expectations • For the second draft: • Ensure the information is technically accurate at the micro level • Ensure the document is reader-focused (usability) • Finalize the design/format • This draft will be reviewed by your content expert and by a peer reviewer

  25. Sample Draft 2

  26. Draft 3: Expectations • For the third draft: • Ensure the guide contains all the relevant graphics • Make a document that is perfect in all aspects by your estimation • Ensure the document is of camera-ready quality • Create a mock-up version of the manual including print, binding, cover, and over-all presentation • You learn many critical lessons prior to final printing by creating a mock-up • The third draft will be reviewed by the instructor

  27. Sample Draft - 3

  28. Overview • The Document Assignment • Flowchart of the Deliverables • Proposal • Functional Specifications • Blueprint • Drafts • Reviews • Final User Guide

  29. Content Expert Reviews • As a content expert, you review the first two drafts created by the writer assigned to your topic • You ensure technical accuracy of the content and improve the overall usability of the document • Your job is NOT to focus on grammar or writing details, rather you are the technical expert and should focus on the subject matter and presentation of the subject matter • Remember that the writer is not bound to use your suggestions, but if they are wise they will honor all content-based recommendations • You will be graded based on the quality of the comments you make to your writer • Use the User Guide Style Guide checklist for review when appropriate

  30. Tips for Content Expert Reviews 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

  31. 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 the target audience, you will provide valuable feedback to the writer to help communicate effectively • Only after you have reviewed the guide many times as an “average Joe” should you go through it again as an “informed classmate” • Use two different color pens: one for “average Joe” and one for “informed classmate” • You will be graded on the quality of the comments you make • Use the User Guide Style Guide checklist for review when you comment as an informed classmate

  32. Tips for Peer Review: “Average Joe” 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

  33. Tips for Peer Review: “Informed Classmate” Look for: • End-user focus • Clarity of tasks and information • An appropriate and helpful style • Adequacy of technical content • Solid overall organization • Parallelism in headings • Adequate white spaces • Consistent formatting • Run-on / incomplete sentences • Active voice • Correct grammar and punctuation

  34. Overview • The Document Assignment • Flowchart of the Deliverables • Proposal • Functional Specifications • Blueprint • Drafts • Reviews • Final User Guide

  35. Final User Guide • The guide will be graded on: • Overall usability • Style • Presentation • Graphics • Accuracy • Fit to audience • Correct application of format, grammar, and punctuation

  36. Final User Guide • Print at least two copies of your final guide: • One (or more) for your professional portfolio • One you will donate to the TWRT department • You may use department printers to save cost • One color printer outside and one inside Prof. Reber’s office are options (please coordinate with her) • Be sure to print in advance • Use good quality paper and binding • You may choose to purchase paper with a classmate

More Related