Creating Your User’s Guide Step-by-Step
M. Reber
© 4/12/2020

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

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

 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
4

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

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

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

 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

 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

 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

11

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

 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




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

 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

16

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




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



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

20

 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

23

 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
24

25

 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

27

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







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

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








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

Look for:
 Parallelism in headings
 Adequate white spaces
 Consistent formatting
 Run-on / incomplete sentences
 Active voice
 Correct punctuation marks
 Grammatically incorrect sentences, such as subjectverb match
 End-user focused
 Adequacy of technical content
 Clarity of tasks
32

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

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

 The guide will be graded on:
 Overall usability
 Style
 Presentation
 Graphics
 Accuracy
 Fit to audience
 Correct application of format, grammar, and punctuation
35

 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