Creating Documentation Your Users Will Love
- 1. Creating Documentation Your Users Will Love Ena Arel
- 2. Overview Top 10 user needs from documentation MathWorks process for capturing content requirements to address user needs Some challenges in developing useful content 2
- 3. Overview Top 10 user needs from documentation MathWorks process for capturing content requirements to address user needs Some challenges in developing useful content 3
- 4. 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 5
- 6. Feature-focused topics make content difficult to find… It’s a miracle I figured it out. The doc says nothing Feature about defining model components! Feature Feature Feature Working with the GT5000
- 7. Information silos also make content difficult to find… Reference Guide User Guide KB Solutions Examples Technical “Which resource Notes should I search to find the topic I need?” 7
- 8. 2 Familiar terminology “I don’t know what you mean by this term… It’s not used in my domain…” 8
- 9. 3 Cues to “skip” or “read” (Quick exit from irrelevant topics) “I’m so glad you described the output up-front. I quickly realized that I need something different.” 9
- 10. 4 Separate topics for “Doing” versus “Learning about” “It’s distracting when I have to learn background information and perform a task at the same time.”
- 11. 5 “Learn” just enough to “Do” “This conceptual information seems important… But how is it relevant to what I need to do in the software…” 11
- 12. 6 Topic titles summarize the topic focus Model Validation Techniques Technique Learn More Compare model output to Simulating and Predicting Model measured output. Output Analyze autocorrelation. Residual Analysis • Impulse and Step Response Plots Plot model response. • Frequency Response Plots Plot model poles and zeros. Pole and Zero Plots Compare model Akaike Akaike Criteria for Model Validation Information Criterion (AIC) 12
- 13. Descriptive titles help users to… Skip to the “answers” they need in a set of related topics. Identify type of content. “This must be conceptual information… I don’t need that right now…” Applications of Frequency Response Models Estimating Frequency Response 13
- 14. 7 Consistent descriptions of the SAME thing 14
- 15. Bluetooth is a… Wireless personal area network (WPAN) for short-range transmission of digital voice and data using omnidirectional radio waves. Short-range wireless technology used to create PANs (Personal Area Networks) among your devices, and with other nearby devices. 15
- 16. Bluetooth is a… “Are these different things, or is Help just being creative?” Wireless personal area network (WPAN) for short-range transmission of digital voice and data using omnidirectional radio waves. Short-range wireless technology used to create PANs (Personal Area Networks) among your devices, and with other nearby devices. 16
- 17. 8 The most efficient path to the goal Create a sinestream signal using the Create a sinestream signal based on a linear frest.SineStream command: model that represents your system dynamics: input = frest.Sinestream input = frest.Sinestream(sys) This command creates a sinetream signal with default settings. sys is the linear model you obtained during exact linearization (see Exact Linearization). For more information about configuring sinestream signals, see For example, create a sinestream signal the frest.Sinestream reference page. from a linearized model: magball io(1) = linio('magball/Desired Height',1); “How would I know what io(2) = linio('magball/Magnetic Ball Plant',... 1,'out'); values to pick? This is way sys = linearize('magball',io); too difficult…” input = frest.Sinestream(sys) 17
- 18. 9 Concrete steps, with examples 1. Open the Simulink model. 1. Open the Simulink model. Example>> 2. Select Simulink blocks for mdl = 'f14'; open_system(mdl) frequency response estimation. 2. Specify the linearization I/O Learn More>> points. This step defines the See Specifying the Linearization Path Simulink blocks for frequency or the linio reference page. response estimation. 3. … Example>> io(1) = linio('f14/Sum1',1) io(2) = linio('f14/Gain5',1,'out') Learn More>> See Specifying the Linearization Path “I don’t want to leave the or the linio reference page. procedure to learn more…” 3. … 18
- 19. 10 Finish what they start 19
- 20. Top 10 Summary 1. Find the topics needed 6. Topic titles summarize to achieve a goal the topic focus 2. Familiar terminology 7. Consistent descriptions 3. Cues to “skip” or “read” of the SAME thing 4. Separate topics for 8. The most efficient path “Doing” versus to the goal “Learning” 9. Concrete steps, with 5. “Learn” just enough examples to “Do” 10. Finish what they start 20
- 21. Overview Top 10 user needs from documentation MathWorks process for capturing content requirements to address user needs Some challenges in developing useful content 21
- 22. 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
- 23. “This is why I bought this product….” Identifies linear and nonlinear models
- 24. “This is why I bought this product!” System Identification Toolbox Getting Started Examples Choosing Your Modeling Approach Data Analysis and Processing Linear Model Identification Identifies linear and nonlinear models 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
- 25. 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
- 26. Capture the workflow that includes possible failures Configure the basics (accept defaults) Execute Evaluate results, decide if good enough Troubleshoot and change settings 26
- 27. Capture the workflow that includes possible failures Configure the basics (accept defaults) Execute Requires decision making information Evaluate results, decide if good enough Troubleshoot and change settings 27
- 28. 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
- 31. 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
- 32. Example of user information needs Questions our user are likely to Task ask about this task. Design the input signal for frequency 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
- 33. What answers address user information needs? Bullets summarize answers to potential user questions. Task Design the input signal for frequency response estimation. ? How do I choose among sinestream vs. chirp signals? When sinestream signals are required A When a chirp signal is good enough A ? How do I validate the signal? A Characteristics of a “good” signal 33
- 34. Now, design the documentation… Xrefs Topics ~ Topic … relationships 34
- 35. Define topics and topic relationships to address content requirements Steady-State Operating Point Exact Frequency Response Analysis (Trimming) Linearization Estimation ~ • When sinestream signals are required About Frequency• When Creating Input Signals a chirp signal is Estimating Frequency … Response Estimation for Estimation Response good enough Choosing Input Creating Sinestream Creating Chirp Signals for Estimation Input Signals Input Signals 35
- 36. Define topics and topic relationships to address content requirements Steady-State Operating Point Exact Frequency Response Analysis (Trimming) Linearization Estimation • Characteristics of a “sinestream” signal • How to design the signal ~ based on a linear system • How to validate the signal About Frequency Creating Input Signals Estimating Frequency … Response Estimation for Estimation using plots Response Choosing Input Defining Sinestream Defining Chirp Signals for Estimation Input Signals Input Signals 36
- 37. Use the information needs as a checklist to validate final doc “Does the doc address how to create and validate signals? If the signal is poor, does it say how to improve the signal?” 37
- 38. Overview Top 10 user needs from documentation MathWorks process for capturing content requirements to address user needs Some challenges in developing useful content 38
- 39. 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
- 40. You are the writer… You shouldn’t really need my input on HOW to document this….
- 41. I’m the content expert! It’s much more efficient if you just take my word for how to update the doc.
- 42. How do we make it easier for customers to use software and documentation together?
- 43. 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
- 44. Thank You! contact information: Ena.Arel@mathworks.com 44
- 45. Writers have legacy documentation that is feature-focused “How do I add new goal-driven topics to feature-focused doc?” “Is there an incremental way to improve documentation while keeping up with the new releases?” 45
Editor's Notes
- #14: Also help make crossreference text descriptive.
- #18: Procedures might also seem inefficient to users when: There are no screenshots to show: GUI selections Sample results Too many alternatives to performing a step, presented inline or as tips Concepts are mixed in with steps, distracting users from the task
- #19: Procedures might also seem vague to users when there are no screenshots to show: GUI selections Sample results
- #20: No links to prerequisites or next steps in a larger workflow might cause users to hit dead ends.
- #24: The MathWorks Our marketing materials describe solutions customers need. After customers buy our products, it would be nice to make it easy for them to learn how to implement that solution – especially the Key Solutions for which they bought the product. However, this version of the Help system makes it difficult - neither searching nor browsing gets customers the Help topics they need to accomplish this goal.