creating documentation your users will love
DESCRIPTION
What are users looking for in technical documentation? This presentation describes 10 best practices in information development based on usability testing.TRANSCRIPT
![Page 1: Creating Documentation Your Users Will Love](https://reader036.vdocuments.us/reader036/viewer/2022070301/546d0216b4af9f6b2c8b51f5/html5/thumbnails/1.jpg)
Creating Documentation Your Users Will Love
Ena Arel
![Page 2: Creating Documentation Your Users Will Love](https://reader036.vdocuments.us/reader036/viewer/2022070301/546d0216b4af9f6b2c8b51f5/html5/thumbnails/2.jpg)
Overview
Top 10 user needs from documentation
MathWorks process for capturing content requirements to address user needs
Some challenges in developing useful content
2
![Page 3: Creating Documentation Your Users Will Love](https://reader036.vdocuments.us/reader036/viewer/2022070301/546d0216b4af9f6b2c8b51f5/html5/thumbnails/3.jpg)
Overview
Top 10 user needs from documentation
MathWorks process for capturing content requirements to address user needs
Some challenges in developing useful content
3
![Page 4: Creating Documentation Your Users Will Love](https://reader036.vdocuments.us/reader036/viewer/2022070301/546d0216b4af9f6b2c8b51f5/html5/thumbnails/4.jpg)
About the Top 10…
Based on industry best practices and usability testing
Presented in no specific order
4
![Page 5: Creating Documentation Your Users Will Love](https://reader036.vdocuments.us/reader036/viewer/2022070301/546d0216b4af9f6b2c8b51f5/html5/thumbnails/5.jpg)
5
1 Find the topics needed to achieve a goal
![Page 6: Creating Documentation Your Users Will Love](https://reader036.vdocuments.us/reader036/viewer/2022070301/546d0216b4af9f6b2c8b51f5/html5/thumbnails/6.jpg)
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
![Page 7: Creating Documentation Your Users Will Love](https://reader036.vdocuments.us/reader036/viewer/2022070301/546d0216b4af9f6b2c8b51f5/html5/thumbnails/7.jpg)
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?”
![Page 8: Creating Documentation Your Users Will Love](https://reader036.vdocuments.us/reader036/viewer/2022070301/546d0216b4af9f6b2c8b51f5/html5/thumbnails/8.jpg)
8
“I don’t know what you mean by this
term… It’s not used in my domain…”
2 Familiar terminology
![Page 9: Creating Documentation Your Users Will Love](https://reader036.vdocuments.us/reader036/viewer/2022070301/546d0216b4af9f6b2c8b51f5/html5/thumbnails/9.jpg)
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)
![Page 10: Creating Documentation Your Users Will Love](https://reader036.vdocuments.us/reader036/viewer/2022070301/546d0216b4af9f6b2c8b51f5/html5/thumbnails/10.jpg)
“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”
![Page 11: Creating Documentation Your Users Will Love](https://reader036.vdocuments.us/reader036/viewer/2022070301/546d0216b4af9f6b2c8b51f5/html5/thumbnails/11.jpg)
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”
![Page 12: Creating Documentation Your Users Will Love](https://reader036.vdocuments.us/reader036/viewer/2022070301/546d0216b4af9f6b2c8b51f5/html5/thumbnails/12.jpg)
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
![Page 13: Creating Documentation Your Users Will Love](https://reader036.vdocuments.us/reader036/viewer/2022070301/546d0216b4af9f6b2c8b51f5/html5/thumbnails/13.jpg)
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
![Page 14: Creating Documentation Your Users Will Love](https://reader036.vdocuments.us/reader036/viewer/2022070301/546d0216b4af9f6b2c8b51f5/html5/thumbnails/14.jpg)
14
7 Consistent descriptions of the SAME thing
![Page 15: Creating Documentation Your Users Will Love](https://reader036.vdocuments.us/reader036/viewer/2022070301/546d0216b4af9f6b2c8b51f5/html5/thumbnails/15.jpg)
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…
![Page 16: Creating Documentation Your Users Will Love](https://reader036.vdocuments.us/reader036/viewer/2022070301/546d0216b4af9f6b2c8b51f5/html5/thumbnails/16.jpg)
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?”
![Page 17: Creating Documentation Your Users Will Love](https://reader036.vdocuments.us/reader036/viewer/2022070301/546d0216b4af9f6b2c8b51f5/html5/thumbnails/17.jpg)
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
![Page 18: Creating Documentation Your Users Will Love](https://reader036.vdocuments.us/reader036/viewer/2022070301/546d0216b4af9f6b2c8b51f5/html5/thumbnails/18.jpg)
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
![Page 19: Creating Documentation Your Users Will Love](https://reader036.vdocuments.us/reader036/viewer/2022070301/546d0216b4af9f6b2c8b51f5/html5/thumbnails/19.jpg)
19
10 Finish what they start
![Page 20: Creating Documentation Your Users Will Love](https://reader036.vdocuments.us/reader036/viewer/2022070301/546d0216b4af9f6b2c8b51f5/html5/thumbnails/20.jpg)
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
![Page 21: Creating Documentation Your Users Will Love](https://reader036.vdocuments.us/reader036/viewer/2022070301/546d0216b4af9f6b2c8b51f5/html5/thumbnails/21.jpg)
Overview
Top 10 user needs from documentation
MathWorks process for capturing content requirements to address user needs
Some challenges in developing useful content
21
![Page 22: Creating Documentation Your Users Will Love](https://reader036.vdocuments.us/reader036/viewer/2022070301/546d0216b4af9f6b2c8b51f5/html5/thumbnails/22.jpg)
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
![Page 23: Creating Documentation Your Users Will Love](https://reader036.vdocuments.us/reader036/viewer/2022070301/546d0216b4af9f6b2c8b51f5/html5/thumbnails/23.jpg)
“This is why I bought this product….”
Identifies linear and nonlinear models
![Page 24: Creating Documentation Your Users Will Love](https://reader036.vdocuments.us/reader036/viewer/2022070301/546d0216b4af9f6b2c8b51f5/html5/thumbnails/24.jpg)
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!”
![Page 25: Creating Documentation Your Users Will Love](https://reader036.vdocuments.us/reader036/viewer/2022070301/546d0216b4af9f6b2c8b51f5/html5/thumbnails/25.jpg)
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
![Page 26: Creating Documentation Your Users Will Love](https://reader036.vdocuments.us/reader036/viewer/2022070301/546d0216b4af9f6b2c8b51f5/html5/thumbnails/26.jpg)
Capture the workflow that includes possible failures
26
Configure the basics (accept defaults)
Execute
Evaluate results, decide if good enough
Troubleshoot and change settings
![Page 27: Creating Documentation Your Users Will Love](https://reader036.vdocuments.us/reader036/viewer/2022070301/546d0216b4af9f6b2c8b51f5/html5/thumbnails/27.jpg)
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
![Page 28: Creating Documentation Your Users Will Love](https://reader036.vdocuments.us/reader036/viewer/2022070301/546d0216b4af9f6b2c8b51f5/html5/thumbnails/28.jpg)
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
![Page 29: Creating Documentation Your Users Will Love](https://reader036.vdocuments.us/reader036/viewer/2022070301/546d0216b4af9f6b2c8b51f5/html5/thumbnails/29.jpg)
29
Capture workflow as a “storyboard”
![Page 30: Creating Documentation Your Users Will Love](https://reader036.vdocuments.us/reader036/viewer/2022070301/546d0216b4af9f6b2c8b51f5/html5/thumbnails/30.jpg)
30
Capture workflowas a code example
![Page 31: Creating Documentation Your Users Will Love](https://reader036.vdocuments.us/reader036/viewer/2022070301/546d0216b4af9f6b2c8b51f5/html5/thumbnails/31.jpg)
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
![Page 32: Creating Documentation Your Users Will Love](https://reader036.vdocuments.us/reader036/viewer/2022070301/546d0216b4af9f6b2c8b51f5/html5/thumbnails/32.jpg)
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
?
?
?
![Page 33: Creating Documentation Your Users Will Love](https://reader036.vdocuments.us/reader036/viewer/2022070301/546d0216b4af9f6b2c8b51f5/html5/thumbnails/33.jpg)
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
![Page 34: Creating Documentation Your Users Will Love](https://reader036.vdocuments.us/reader036/viewer/2022070301/546d0216b4af9f6b2c8b51f5/html5/thumbnails/34.jpg)
Now, design the documentation…
34
~
…
Topics
Topic relationships
Xrefs
![Page 35: Creating Documentation Your Users Will Love](https://reader036.vdocuments.us/reader036/viewer/2022070301/546d0216b4af9f6b2c8b51f5/html5/thumbnails/35.jpg)
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
![Page 36: Creating Documentation Your Users Will Love](https://reader036.vdocuments.us/reader036/viewer/2022070301/546d0216b4af9f6b2c8b51f5/html5/thumbnails/36.jpg)
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
![Page 37: Creating Documentation Your Users Will Love](https://reader036.vdocuments.us/reader036/viewer/2022070301/546d0216b4af9f6b2c8b51f5/html5/thumbnails/37.jpg)
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?”
![Page 38: Creating Documentation Your Users Will Love](https://reader036.vdocuments.us/reader036/viewer/2022070301/546d0216b4af9f6b2c8b51f5/html5/thumbnails/38.jpg)
Overview
Top 10 user needs from documentation
MathWorks process for capturing content requirements to address user needs
Some challenges in developing useful content
38
![Page 39: Creating Documentation Your Users Will Love](https://reader036.vdocuments.us/reader036/viewer/2022070301/546d0216b4af9f6b2c8b51f5/html5/thumbnails/39.jpg)
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
![Page 40: Creating Documentation Your Users Will Love](https://reader036.vdocuments.us/reader036/viewer/2022070301/546d0216b4af9f6b2c8b51f5/html5/thumbnails/40.jpg)
You are the writer… You
shouldn’t really need my input on HOW to document
this….
![Page 41: Creating Documentation Your Users Will Love](https://reader036.vdocuments.us/reader036/viewer/2022070301/546d0216b4af9f6b2c8b51f5/html5/thumbnails/41.jpg)
I’m the content expert! It’s much more efficient if you just take my word for how to update the
doc.
![Page 42: Creating Documentation Your Users Will Love](https://reader036.vdocuments.us/reader036/viewer/2022070301/546d0216b4af9f6b2c8b51f5/html5/thumbnails/42.jpg)
How do we make it easier for customers to use software and
documentation together?
![Page 43: Creating Documentation Your Users Will Love](https://reader036.vdocuments.us/reader036/viewer/2022070301/546d0216b4af9f6b2c8b51f5/html5/thumbnails/43.jpg)
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