Creating Documentation Your Users Will Love
44
Creating Documentation Your Users Will Love Ena Arel
-
Upload
ena-arel -
Category
Technology
-
view
143 -
download
4
description
What are users looking for in technical documentation? This presentation describes 10 best practices in information development based on usability testing.
Transcript of Creating Documentation Your Users Will Love
Creating Documentation Your Users Will Love
Ena Arel
Overview
Top 10 user needs from documentation
MathWorks process for capturing content requirements to address user needs
Some challenges in developing useful content
2
Overview
Top 10 user needs from documentation
MathWorks process for capturing content requirements to address user needs
Some challenges in developing useful content
3
About the Top 10…
Based on industry best practices and usability testing
Presented in no specific order
4
5
1 Find the topics needed to achieve a goal
Feature-focused topics make contentdifficult to find…
It’s a miracle I figured it out.
The doc says nothing about defining model
components! Feature
Feature
Feature
Feature
Working with the GT5000
Information silos also make contentdifficult to find…
7
User Guide
Examples
ReferenceGuide
KBSolutions
Technical Notes
“Which resource should I search to
find the topic I need?”
8
“I don’t know what you mean by this
term… It’s not used in my domain…”
2 Familiar terminology
9
“I’m so glad you described the output up-front. I quickly
realized that I need something different.”
3 Cues to “skip” or “read” (Quick exit from irrelevant topics)
“It’s distracting when I have to learn background
information and perform a task at the same time.”
4 Separate topics for “Doing” versus “Learning about”
11
“This conceptual information seems important…
But how is it relevant to what I need to do in the
software…”
5 “Learn” just enough to “Do”
12
Model Validation Techniques
Technique Learn More
Compare model output to measured output.
Simulating and Predicting Model Output
Analyze autocorrelation. Residual Analysis
Plot model response.• Impulse and Step Response Plots• Frequency Response Plots
Plot model poles and zeros. Pole and Zero Plots
Compare model Akaike Information Criterion (AIC)
Akaike Criteria for Model Validation
6 Topic titles summarize the topic focus
Descriptive titles help users to…
Skip to the “answers” they need in a set of related topics.
Identify type of content.
13
“This must be conceptual information… I don’t need
that right now…”
Applications of Frequency Response Models
Estimating Frequency Response
14
7 Consistent descriptions of the SAME thing
Wireless personal area network (WPAN) for short-range transmission of digital voice and data using omnidirectional radio waves.
15
Short-range wireless technology used to create PANs (Personal Area Networks) among your devices, and with other nearby devices.
Bluetooth is a…
Wireless personal area network (WPAN) for short-range transmission of digital voice and data using omnidirectional radio waves.
16
Short-range wireless technology used to create PANs (Personal Area Networks) among your devices, and with other nearby devices.
Bluetooth is a… “Are these different things, or is Help just being
creative?”
Create a sinestream signal using the frest.SineStream command:
input = frest.Sinestream
This command creates a sinetream signal with default settings.
For more information about configuring sinestream signals, see the frest.Sinestream reference page.
Create a sinestream signal based on a linear model that represents your system dynamics:
input = frest.Sinestream(sys)
sys is the linear model you obtained during exact linearization (see Exact Linearization).
For example, create a sinestream signal from a linearized model:
magball
io(1) = linio('magball/Desired Height',1);
io(2) = linio('magball/Magnetic Ball Plant',...
1,'out');
sys = linearize('magball',io);
input = frest.Sinestream(sys)
17
“How would I know what values to pick? This is way
too difficult…”
8 The most efficient path to the goal
1. Open the Simulink model. Example>>
mdl = 'f14'; open_system(mdl)
2. Specify the linearization I/O points. This step defines the Simulink blocks for frequency response estimation. Example>> io(1) = linio('f14/Sum1',1) io(2) = linio('f14/Gain5',1,'out')
Learn More>>
See Specifying the Linearization Path or the linio reference page.
3. …
1. Open the Simulink model.
2. Select Simulink blocks for frequency response estimation. Learn More>> See Specifying the Linearization Path or the linio reference page.
3. …
18
“I don’t want to leave the procedure to learn more…”
9 Concrete steps, with examples
19
10 Finish what they start
Top 10 Summary
1. Find the topics needed to achieve a goal
2. Familiar terminology
3. Cues to “skip” or “read”
4. Separate topics for “Doing” versus “Learning”
5. “Learn” just enough to “Do”
6. Topic titles summarize the topic focus
7. Consistent descriptions of the SAME thing
8. The most efficient path to the goal
9. Concrete steps, with examples
10. Finish what they start
20
Overview
Top 10 user needs from documentation
MathWorks process for capturing content requirements to address user needs
Some challenges in developing useful content
21
Before writing, discuss with the product team…
1. How do users use the product to accomplish their goals? (goals, motivation, steps)
2. What questions are users likely to ask while using the software? (information needs)
3. What answers address user information needs? (content requirements)
22
“This is why I bought this product….”
Identifies linear and nonlinear models
Identifies linear and nonlinear models
Getting Started
Examples
Choosing Your Modeling Approach
Data Analysis and Processing
Linear Model Identification
Nonlinear Model Identification
ODE Parameter Estimation (Grey Box Modeling)
Time Series Identification
Recursive Identification Techniques
Model Analysis
Simulation and Prediction
Using Identified Models in Control Design
System Identification in Simulink
Function Reference
Block Reference
System Identification Toolbox
“This is why I bought this product!”
How do users use the product to accomplish their goals?
“How do users phrase their problem or goal?” “How will users apply the results?”
(related or extended workflows)
“Any limitations on the results?” (If limitation are not acceptable, what should users do instead?)
“Any special setup requirements?” (it won’t work unless they do this)
25
Capture the workflow that includes possible failures
26
Configure the basics (accept defaults)
Execute
Evaluate results, decide if good enough
Troubleshoot and change settings
Capture the workflow that includes possible failures
27
Configure the basics (accept defaults)
Execute
Evaluate results, decide if good enough
Troubleshoot and change settings
Requires decision making
information
Identify task steps
“Show me how user will achieve their goal in the software…” (can use paper prototypes)
“What do users call the incremental results in their workflow?”
28
29
Capture workflow as a “storyboard”
30
Capture workflowas a code example
What questions are users likely to ask while using the software?
“What are users likely to find challenging while doing each step?” (potential pain points)
“How do they interpret results?”(What parts of the output are not self-explanatory?)
“How do they evaluate results?” (Any error or warning messages?)
“How can they improve results?” (Analyze the problem and make decisions about different options)
31
Example of user information needs
Design the input signal forfrequency response estimation.
How do I choose among sinestream vs. chirp signals?
How do I validate the signal?
How do I modify a poor signal?
32
Questions our user are likely to ask about this task.Task
?
?
?
What answers address user information needs?
Design the input signal forfrequency response estimation.
How do I choose among sinestream vs. chirp signals?
When sinestream signals are required
When a chirp signal is good enough
How do I validate the signal?
Characteristics of a “good” signal
33
Task
Bullets summarize answers to potential user questions.
?
?
A
A
A
Now, design the documentation…
34
~
…
Topics
Topic relationships
Xrefs
Define topics and topic relationships to address content requirements
35
Steady-State Operating PointAnalysis (Trimming)
ExactLinearization
Frequency ResponseEstimation
About Frequency Response Estimation
Estimating FrequencyResponse
Choosing InputSignals for Estimation
Creating SinestreamInput Signals
Creating ChirpInput Signals
Creating Input Signalsfor Estimation
~
…
• When sinestream signals are required
• When a chirp signal is good enough
Define topics and topic relationships to address content requirements
36
Steady-State Operating PointAnalysis (Trimming)
ExactLinearization
Frequency ResponseEstimation
About Frequency Response Estimation
Estimating FrequencyResponse
Defining SinestreamInput Signals
Defining ChirpInput Signals
Creating Input Signalsfor Estimation
~
…
• Characteristics of a “sinestream” signal
• How to design the signal based on a linear system
• How to validate the signal using plots
Choosing InputSignals for Estimation
Use the information needs as a checklist to validate final doc
37
“Does the doc address how to create and validate signals?
If the signal is poor, does it say how to improve the signal?”
Overview
Top 10 user needs from documentation
MathWorks process for capturing content requirements to address user needs
Some challenges in developing useful content
38
Does the team agree about what users need from the doc?
Developers often have a feature focus– “Describe what the feature does, how it works, and all the
options…”
Writers have a user focus– “Describe how to use the feature to accomplish goals.”
– “Tell user how it works only when if it helps them to use the feature better.”
– “Reduce complexity by guiding users to choose specific options.”
39
You are the writer… You
shouldn’t really need my input on HOW to document
this….
I’m the content expert! It’s much more efficient if you just take my word for how to update the
doc.
How do we make it easier for customers to use software and
documentation together?
Summary
Users want find documentation and find it useful for solving their problems.
MathWorks process for content requirements focuses on identifying potential user questions and audience-appropriate answers.
Content requirements can be used as a checklist for validating documentation design.
43
