M. Reber © 5/1/2015 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 2

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

The Document Assignment The culminating product of the assignment is a page camera-ready, portfolio-quality user’s guide  Research, analyze, plan, schedule, design, write, and evaluate a 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 4

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

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

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

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

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 9

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 10

Sample Proposal 11

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

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 13

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 14

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 15

Sample Functional Specification 16

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

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 18

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 19

Sample Blueprint 20

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

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 22 Draft 1: Expectations

Sample Draft 1 23

Draft 2: Expectations 24 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

Sample Draft 2 25

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 26

Sample Draft

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

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 29

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 30

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 31

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 32

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 33

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

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 35

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 36