-
Notifications
You must be signed in to change notification settings - Fork 1
/
trouble-with-troubleshooting.html
170 lines (157 loc) · 14.4 KB
/
trouble-with-troubleshooting.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="author" content="Jared Morgan"><title>The trouble with troubleshooting</title><meta content="yes" name="apple-mobile-web-app-capable"><meta content="black-translucent" name="apple-mobile-web-app-status-bar-style"><meta content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, minimal-ui" name="viewport"><link href="reveal.js/css/reveal.css" rel="stylesheet"><link rel="stylesheet" href="reveal.js/css/theme/league.css" id="theme"><!--This CSS is generated by the Asciidoctor-Reveal.js converter to further integrate AsciiDoc's existing semantic with Reveal.js--><style type="text/css">.reveal div.right {
float: right;
}
/* callouts */
.conum[data-value] {display:inline-block;color:#fff!important;background-color:rgba(50,150,50,.8);-webkit-border-radius:100px;border-radius:100px;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:"Open Sans","DejaVu Sans",sans-serif;font-style:normal;font-weight:bold}
.conum[data-value] *{color:#fff!important}
.conum[data-value]+b{display:none}
.conum[data-value]:after{content:attr(data-value)}
pre .conum[data-value]{position:relative;top:-.125em}
b.conum *{color:inherit!important}
.conum:not([data-value]):empty{display:none}</style><link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.3.0/css/font-awesome.min.css"><link href="reveal.js/lib/css/zenburn.css" rel="stylesheet"><script>var link = document.createElement( 'link' );
link.rel = 'stylesheet';
link.type = 'text/css';
link.href = window.location.search.match( /print-pdf/gi ) ? "reveal.js/css/print/pdf.css" : "reveal.js/css/print/paper.css";
document.getElementsByTagName( 'head' )[0].appendChild( link );</script><!--[if lt IE 9]><script src="reveal.js/lib/js/html5shiv.js"></script><![endif]--></head><body><div class="reveal"><div class="slides"><section class="title" data-state="title"><h1>The trouble with troubleshooting</h1><p class="author"><small>Jared Morgan</small></p></section><section id="_hi_im_jared_morgan"><h2>Hi I’m Jared Morgan</h2><div class="ulist step"><ul><li class="fragment"><p><a href="mailto:jaredleonmorgan@gmail.com">jaredleonmorgan@gmail.com</a></p></li><li class="fragment"><p><a href="https://twitter.com/jaredmorgs">@jaredmorgs</a></p></li><li class="fragment"><p><a href="https://writethedocs.slack.com" class="bare">https://writethedocs.slack.com</a> #general room.</p></li><li class="fragment"><p><a href="https://slack.thegooddocsproject.dev" class="bare">https://slack.thegooddocsproject.dev</a></p></li></ul></div></section>
<section id="_troubleshooting"><h2>Troubleshooting</h2><div class="paragraph"><p>Everything malfunctions eventually.</p></div>
<div class="paragraph"><p>When it does you rely on troubleshooting sections in docs to solve your problems.</p></div></section>
<section><section id="_troubleshooting_done_right"><h2>Troubleshooting done right</h2><div class="paragraph"><p>Troubleshooting steps should do the following:</p></div><div class="ulist"><ul><li><p>Re-assure you that "you’ve got this"</p></li><li><p>Give you just enough info to solve the problem</p></li><li><p>Be mindful of your mental state</p></li><li><p>Give you a path when troubleshooting fails.</p></li></ul></div></section><section><div class="paragraph"><p>When done well you get users reacting like this:</p></div>
<div class="imageblock" style=""><img src="images/shock.jpg" alt="Photo by Ben White on Unsplash" width="background"></div></section></section>
<section><section id="_troubleshooting_done_wrong"><h2>Troubleshooting done wrong</h2><div class="paragraph"><p>When troubleshooting is not done well…​</p></div></section><section id="_it_causes_frustration" class="red background"><h2>It causes frustration</h2><div class="imageblock" style=""><img src="images/frustration.jpg" alt="Photo by FuYong Hua on Unsplash"></div></section><section id="_support_calls"><h2>Support calls</h2><div class="imageblock" style=""><img src="images/calls.jpg" alt="Photo by Icons8 Team on Unsplash"></div></section><section id="_no_love_on_the_internets_for_your_business"><h2>No love on the internets for your business</h2><div class="imageblock" style=""><img src="images/socials.jpg" alt="Photo by Prateek Katyal on Unsplash"></div></section></section>
<section id="_why_does_troubleshooting_often_fail"><h2>Why does troubleshooting often fail?</h2><div class="ulist"><ul><li><p>You don’t understand how your audience scans your docs.</p></li><li><p>You don’t focus on symptoms.</p></li><li><p>You don’t consider how they might be feeling at the time.</p></li><li><p>You don’t solve their problem!</p></li></ul></div></section>
<section><section id="_the_trouble_with_blenders"><h2>The trouble with blenders</h2><div class="paragraph"><p>When they work, they are fantastic.</p></div><div class="paragraph"><p>When they stop half-way through a blend…​</p></div></section><section><div class="paragraph"><p>You want to do this to them…​</p></div>
<div class="imageblock" style=""><img src="images/blender.gif" alt="blender"></div></section></section>
<section><section id="_scenario" data-background-image="images/acai-before.jpg" data-background-size="contain"><h2>Scenario</h2></section><section data-background-image="images/acai-after.jpg" data-background-size="contain"></section><section data-background-image="images/manual.jpg" data-background-size="contain"></section><section data-background-image="images/troubleshooting.jpg" data-background-size="contain"></section><section data-background-image="images/troubleshooting-section.jpg" data-background-size="contain"><div class="paragraph"><p>Huh? What’s this about Interlock herbidy glerbity blerty blergh</p></div></section></section>
<section><section id="_why_did_these_steps_fail_for_me"><h2>Why did these steps fail for me?</h2><div class="ulist"><ul><li><p>Couldn’t find the symptom: "flashing status light"</p></li><li><p>Didn’t emphathise with my mental state: "frustrated"</p></li><li><p>Used Jargon: "Interlock Protection" (dude WTF),</p></li><li><p>…​blender will need to be reset if the interlock is not properly engaged.</p></li></ul></div></section><section><div class="imageblock" style=""><img src="images/troubleshooting-section.jpg" alt="troubleshooting section"></div></section><section id="_how_i_was_feeling_after_reading_this"><h2>How I was feeling after reading this</h2><div class="paragraph"><p>"Reset the flamin' blender?"</p></div>
<div class="paragraph"><p>"How long is that going to take"</p></div>
<div class="paragraph"><p>"They’re getting a frickin' email about this X-("</p></div>
<div class="paragraph"><p>"Guess I’m having granola for breakfast…​"</p></div></section></section>
<section id="_i_sent_them_an_email"><h2>I sent them an email…​</h2><div class="paragraph"><p>It took them two days to get back to me.</p></div>
<div class="paragraph"><p>They asked me for my serial number?</p></div>
<div class="paragraph"><p>What does that have to do with status lights?</p></div>
<div class="paragraph"><p>Frustration > Indifference > TECH WRITING!!!!</p></div></section>
<section><section id="_i_sent_them_revised_copy"><h2>I sent them revised copy</h2></section><section id="_symptom"><h2>Symptom</h2><div class="paragraph"><p>Blender Light Is Flashing</p></div></section><section id="_condition"><h2>Condition</h2><div class="paragraph"><p>The status light on your blender blinks at different rates (slow, solid, fast).</p></div>
<div class="paragraph"><p>This happens when the blender bowl interlock or temperature sensors detect a problem.</p></div></section><section id="_solution"><h2>Solution</h2><div class="paragraph"><p>You can often solve these problems by reading the explanation and troubleshooting steps for each light sequence on page 8 of this manual.</p></div></section><section id="_if_all_else_fails"><h2>If all else fails</h2><div class="paragraph"><p>If you still have problems with your blender after troubleshooting the issue, contact Customer Support through the numbers and methods in the back of your manual.</p></div></section></section>
<section id="_do_it_right_or_dont_do_it"><h2>Do it right, or don’t do it</h2><div class="paragraph"><p>Troubleshooting is useless if it doesn’t help your customers solve problems in their language.</p></div>
<div class="paragraph"><p>Talk to your users.</p></div>
<div class="paragraph"><p>Understand their needs.</p></div>
<div class="paragraph"><p>Fix their problems.</p></div></section>
<section id="_say_gday"><h2>Say G’day</h2><div class="ulist"><ul><li><p><a href="mailto:jaredleonmorgan@gmail.com">jaredleonmorgan@gmail.com</a></p></li><li><p><a href="https://twitter.com/jaredmorgs">@jaredmorgs</a></p></li><li><p><a href="https://writethedocs.slack.com" class="bare">https://writethedocs.slack.com</a> #general room.</p></li><li><p><a href="https://slack.thegooddocsproject.dev" class="bare">https://slack.thegooddocsproject.dev</a></p></li></ul></div></section></div></div><script src="reveal.js/lib/js/head.min.js"></script><script src="reveal.js/js/reveal.js"></script><script>Array.prototype.slice.call(document.querySelectorAll('.slides section')).forEach(function(slide) {
if (slide.getAttribute('data-background-color')) return;
// user needs to explicitly say he wants CSS color to override otherwise we might break custom css or theme (#226)
if (!(slide.classList.contains('canvas') || slide.classList.contains('background'))) return;
var bgColor = getComputedStyle(slide).backgroundColor;
if (bgColor !== 'rgba(0, 0, 0, 0)' && bgColor !== 'transparent') {
slide.setAttribute('data-background-color', bgColor);
slide.style.backgroundColor = 'transparent';
}
})
// See https://github.com/hakimel/reveal.js#configuration for a full list of configuration options
Reveal.initialize({
// Display presentation control arrows
controls: true,
// Help the user learn the controls by providing hints, for example by
// bouncing the down arrow when they first encounter a vertical slide
controlsTutorial: true,
// Determines where controls appear, "edges" or "bottom-right"
controlsLayout: 'bottom-right',
// Visibility rule for backwards navigation arrows; "faded", "hidden"
// or "visible"
controlsBackArrows: 'faded',
// Display a presentation progress bar
progress: true,
// Display the page number of the current slide
slideNumber: 'true',
// Control which views the slide number displays on
showSlideNumber: 'all',
// Push each slide change to the browser history
history: false,
// Enable keyboard shortcuts for navigation
keyboard: true,
// Enable the slide overview mode
overview: true,
// Vertical centering of slides
center: true,
// Enables touch navigation on devices with touch input
touch: true,
// Loop the presentation
loop: false,
// Change the presentation direction to be RTL
rtl: false,
// Randomizes the order of slides each time the presentation loads
shuffle: false,
// Turns fragments on and off globally
fragments: true,
// Flags whether to include the current fragment in the URL,
// so that reloading brings you to the same fragment position
fragmentInURL: false,
// Flags if the presentation is running in an embedded mode,
// i.e. contained within a limited portion of the screen
embedded: false,
// Flags if we should show a help overlay when the questionmark
// key is pressed
help: true,
// Flags if speaker notes should be visible to all viewers
showNotes: false,
// Global override for autolaying embedded media (video/audio/iframe)
// - null: Media will only autoplay if data-autoplay is present
// - true: All media will autoplay, regardless of individual setting
// - false: No media will autoplay, regardless of individual setting
autoPlayMedia: null,
// Number of milliseconds between automatically proceeding to the
// next slide, disabled when set to 0, this value can be overwritten
// by using a data-autoslide attribute on your slides
autoSlide: 0,
// Stop auto-sliding after user input
autoSlideStoppable: true,
// Use this method for navigation when auto-sliding
autoSlideMethod: Reveal.navigateNext,
// Specify the average time in seconds that you think you will spend
// presenting each slide. This is used to show a pacing timer in the
// speaker view
defaultTiming: 120,
// Enable slide navigation via mouse wheel
mouseWheel: false,
// Hides the address bar on mobile devices
hideAddressBar: true,
// Opens links in an iframe preview overlay
// Add `data-preview-link` and `data-preview-link="false"` to customise each link
// individually
previewLinks: false,
// Transition style (e.g., none, fade, slide, convex, concave, zoom)
transition: 'concave',
// Transition speed (e.g., default, fast, slow)
transitionSpeed: 'default',
// Transition style for full page slide backgrounds (e.g., none, fade, slide, convex, concave, zoom)
backgroundTransition: 'fade',
// Number of slides away from the current that are visible
viewDistance: 3,
// Parallax background image (e.g., "'https://s3.amazonaws.com/hakim-static/reveal-js/reveal-parallax-1.jpg'")
parallaxBackgroundImage: '',
// Parallax background size in CSS syntax (e.g., "2100px 900px")
parallaxBackgroundSize: '',
// Number of pixels to move the parallax background per slide
// - Calculated automatically unless specified
// - Set to 0 to disable movement along an axis
parallaxBackgroundHorizontal: null,
parallaxBackgroundVertical: null,
// The display mode that will be used to show slides
display: 'block',
// The "normal" size of the presentation, aspect ratio will be preserved
// when the presentation is scaled to fit different resolutions. Can be
// specified using percentage units.
width: 960,
height: 700,
// Factor of the display size that should remain empty around the content
margin: 0.1,
// Bounds for smallest/largest possible scale to apply to content
minScale: 0.2,
maxScale: 1.5,
// Optional libraries used to extend on reveal.js
dependencies: [
{ src: 'reveal.js/lib/js/classList.js', condition: function() { return !document.body.classList; } },
{ src: 'reveal.js/plugin/zoom-js/zoom.js', async: true },
{ src: 'reveal.js/plugin/notes/notes.js', async: true },
{ src: 'reveal.js/plugin/print-pdf/print-pdf.js', async: true },
],
});</script></body></html>