Nick Cernis - writingZola2018-02-14T00:00:00+00:00https://www.nickcernis.com/tags/writing/atom.xml“This cookie is frowning” and other bug reports2018-02-14T00:00:00+00:002018-02-14T00:00:00+00:00https://www.nickcernis.com/blog/best-bug-reports/<p>I collect silly bug reports to remind me that computers are hard. Here are my favourites so far:</p>
<h2 id="the-cookie-is-frowning">The cookie is frowning</h2>
<p>From <a href="https://openradar.appspot.com/22651414">Apple Open Radar report #22651414</a>.</p>
<blockquote>
<p>The Cookie Emoji (🍪 U+1F36A) is frowning. I mean just look at this thing (attached screenshot)! It doesn’t look frowning when it’s big, only when it’s small. Cookies are supposed to be happy! Same problem on iOS and watchOS.</p>
<p>Steps to Reproduce:</p>
<ol>
<li>Send a cookie emoji character (U+1F36A) to yourself in a messaging app (iMessage is fine).</li>
<li>Look at that tiny frowning cookie!</li>
</ol>
<p>Expected Results:<br />
Cookies should be happy.</p>
<p>Actual Results:<br />
This cookie is frowning.</p>
<p>Version:<br />
10.11 Beta (15A278b)</p>
</blockquote>
<h2 id="my-cat-sat-on-my-laptop-and-now-the-right-side-of-the-keyboard-types-the-wrong-characters">My cat sat on my laptop and now the right side of the keyboard types the wrong characters</h2>
<p>It’s the age-old story: pet sits on laptop, laptop proves incompatible with pet.</p>
<p><a href="https://superuser.com/questions/1143100/my-cat-sat-on-my-laptop-now-the-right-side-of-my-keyboard-types-the-wrong-chara">See the response here</a>.</p>
<h2 id="my-car-won-t-start-when-i-buy-vanilla-ice-cream-it-s-fine-with-chocolate">My car won’t start when I buy vanilla ice cream (it’s fine with chocolate)</h2>
<p>This is a short and wonderful story of ice cream, patience, and a dedicated engineer that’s too good to spoil by summarising. I recommend reading <a href="https://www.snopes.com/fact-check/cone-of-silence/">the whole thing here</a>.</p>
<p>Their own summary is apt, though:</p>
<blockquote>
<p>Moral of the story: even insane-looking problems are sometimes real.</p>
</blockquote>
<h2 id="i-can-t-log-in-when-i-m-standing-up">I can’t log in when I’m standing up</h2>
<p>From the ever-frightening <a href="https://www.reddit.com/r/talesfromtechsupport/">Tales From Tech Support</a> subreddit.</p>
<blockquote>
<p>One day a sysadmin gets a call from the factory floor and after the usual pleasantries the user says:</p>
<p>I can’t log in when I stand up.</p>
<p>The sysadmin thinks that it’s one of those calls again and goes through the usual:</p>
<p>Is the power on? What do you see on the terminal? Have you forgotten your password?</p>
<p>The user interrupts:</p>
<p>I know what I’m doing, when I sit down I can log in and everything works, but I can’t log in when I stand up.</p>
</blockquote>
<p>The <a href="https://www.reddit.com/r/talesfromtechsupport/comments/3v52pw/i_cant_log_in_when_i_stand_up/">story continues here</a>, and I want to believe it’s real.</p>
<h2 id="we-can-t-send-email-more-than-500-miles">We can’t send email more than 500 miles</h2>
<p>I started reading <a href="http://www.ibiblio.org/harris/500milemail.html">this report on email limited to a physical distance of 500 miles</a> with great skepticism that such a thing could ever present itself. I finished with “Ah, of course. The speed of light!” The power of heroic support work and an open and inquisitive mind.</p>
<h2 id="why-does-subtracting-two-dates-in-1927-that-were-one-second-apart-give-me-353-seconds">Why does subtracting two dates in 1927 that were one second apart give me 353 seconds?</h2>
<p>Jon Skeet’s <a href="https://stackoverflow.com/a/6841479/88487">famous answer</a> to a thorny date-time question is one of those <em>but, of course! — it’s broken on purpose</em> moments that programmers encounter every week:</p>
<blockquote>
<p>It’s a time zone change on December 31st in Shanghai.</p>
<p>Basically at midnight at the end of 1927, the clocks went back 5 minutes and 52 seconds. So “1927-12-31 23:54:08” actually happened twice, and it looks like Java is parsing it as the later possible instant for that local date/time — hence the difference.</p>
</blockquote>
<p>See also: <a href="https://www.youtube.com/watch?v=-5wpm-gesOY">Time zones are hard</a>.</p>
<h2 id="why-do-i-see-gimme-gimme-gimme-in-man-output">Why do I see “Gimme gimme gimme” in <code>man</code> output?</h2>
<p>From the department of <em>Accidental Easter Eggs</em> comes this story of an <a href="https://unix.stackexchange.com/questions/405783/why-does-man-print-gimme-gimme-gimme-at-0030">ABBA lyric snuck into the source</a> of a hugely popular command line utility.</p>
<p>The top-voted answer is lovely:</p>
<blockquote>
<p>er, that was my fault, I suggested it. Sorry.</p>
</blockquote>
<h2 id="the-bug-in-the-machine">The bug in the machine</h2>
<p>From the <a href="https://en.wikipedia.org/wiki/Software_bug#Etymology">“original” bug report</a> where a moth was found in a relay, cited as the cause of a bug, and physically taped to the report:</p>
<img src="/images/blog/first-computer-bug-1945.jpg" alt="Photograph of a moth retrieved from a relay">
How to answer a support request2018-02-14T00:00:00+00:002018-02-14T00:00:00+00:00https://www.nickcernis.com/blog/how-to-answer-a-support-request/<h2 id="lift-the-outcome-to-the-surface">Lift the outcome to the surface</h2>
<p>Think: <em>what does this person most want to hear from me?</em> Normally this is, “we have fixed your problem”. So put that part first.</p>
<p>In the same way <a href="https://nickcernis.com/blog/how-to-answer-a-support-request/">a good support request</a> starts with the problem statement or question unburdened by four paragraphs of free-form beat poetry as preamble, a good response should start with the outcome.</p>
<p>It can be tempting to explain the great lengths you undertook to fix an issue, particularly if it took weeks to resolve and you are now feeling very proud of yourself or your team:</p>
<blockquote>
<p>Hi Bob</p>
<p>Thank you for your patience with this.</p>
<p>We conducted a thorough investigation, liaised with our development team, and identified an issue with sprocket 14 in the flanging manifold, which had a broken tooth due to malnutrition. Hellcat 27 was deployed to fix this and made a successful repair.</p>
<p>As a result, your ears will no longer explode spontaneously when logging in to your account.</p>
</blockquote>
<p>Better is this:</p>
<blockquote>
<p>Hi Bob</p>
<p>Your ears will no longer explode when you log in now.</p>
<p>The cause was a hardware defect. We replaced a part and have adjusted our maintenance schedule to prevent this from occurring again. I’m happy to share technical details if you’d like to know more.</p>
<p>I’m so sorry for the distress this caused. We’re providing you with a lifetime of free cake to thank you for your patience while we investigated. Please let me know if I can help further.</p>
</blockquote>
<p>Your response to the trickiest problem should be along the lines of, “we have taken care of that for you” without the prepended or appended, “sheesh, this one was really hard to fix — it’s a good job we’re so smart!”</p>
<h2 id="avoid-boilerplate">Avoid boilerplate</h2>
<p>Many battle-worn support aardvarks use snippet applications such as TextExpander. If you must use them — perhaps because your employer is a victim of Goodhart’s law (“when a metric becomes a target, it becomes a bad metric”) — it’s worth personalising your snippets and dropping any that smell <em>too snippety</em>.</p>
<p>Customers can smell boilerplate in the skeleton of your reply before they’ve even read it; snippets <em>look</em> impersonal if you mostly email people who type all their words by hand. People hate the feeling that you’ve picked your response from a list. Try cutting down.</p>
<p>And, yes, support work can be repetitive and snippets may be a blessing. But if everyone on your team is parroting similar responses to similar questions, it is a sign that your product, documentation, contextual help, or pre-sales and pre-support info could be tweaked.</p>
<h2 id="avoid-boilerplate-ese">Avoid boilerplate-ese</h2>
<p>Boilerplate-ese is text you wrote by hand that looks like it was auto-generated or copied from a crib sheet or snippet. Text like:</p>
<blockquote>
<p>Thanks for your feature request! I recorded your vote in the voting shredder. Thank you for purchasing a Funkotronic 5000. Have a great day!</p>
</blockquote>
<p>There is nothing here that acknowledges your customer’s unique request, so it feels canned even if you hand-typed every letter. Better would be:</p>
<blockquote>
<p>Thank you for this suggestion. We do not currently have plans to add exploding bees to the Funkotronic, as it would present safety issues for people and for the bees.</p>
<p>If you have other ideas for us in the future, though, please feel free to share them.</p>
</blockquote>
<h2 id="drop-sorry-not-sorry-phrases">Drop “sorry not sorry” phrases</h2>
<p>“We apologise for the inconvenience” is not empathetic. It reads like a government-issued notice, devoid of any compassion at all:</p>
<blockquote>
<p>To whom it may concern:</p>
<p>Your son is considered defective and has been recalled. We apologise for any inconvenience caused.</p>
<p>Sincerely<br />
The Ministry of Recycling</p>
</blockquote>
<p>I like to use other phrases that appear to mean the same thing:</p>
<ul>
<li>I’m sorry for the extra work this caused you…</li>
<li>I’m sorry for the time you’ve lost on this…</li>
<li>I’m sorry for our mistake here…</li>
</ul>
<p>These turn the impersonal ‘we’ into ‘I’, accept the blame, or they recognise that the person lost more than the “convenience” of having the product or service they pay for work correctly.</p>
<h2 id="skip-the-blame-words">Skip the blame words</h2>
<p>“You” and “your” are the most common blame words:</p>
<blockquote>
<p>“Your site is broken because of a change you made on line 1234.”</p>
</blockquote>
<p>…would be better expressed as:</p>
<blockquote>
<p>“The site is broken because of a change on line 1234.”</p>
</blockquote>
<p>This is passive on purpose: it absolves your customer of blame and avoids a fight. And, besides, it’s presumptious to say they introduced a change that broke their thing. Keyboards hold an amazing magnetism for cats, kids, and other tiny meddlers.</p>
<p>Also watch for “should not”, “must not” and variants:</p>
<blockquote>
<p>“You should never do it that way.”</p>
</blockquote>
<p>Better is:</p>
<blockquote>
<p>“We recommend doing it this way…”</p>
</blockquote>
<p>The job of a support team is to make people feel happy, not guilty.</p>
<h2 id="easy-on-the-exclamation-marks">Easy on the exclamation marks</h2>
<p>How do you express that you’re a cheery support person who’s genuinely happy to solve people’s problems? Email makes this tough. It can be tempting to drop exclamation points like hot potatoes to show that you’re happy and responsive.</p>
<p>Try mirroring the mood of your customer without ever dropping your own tone below “nice”. Does your customer use smilies? Mirror that in your response. Do they use emphatic sign-offs (“thanks so much!!!”)? Then perhaps it’s okay to throw in a single exclamation point in your sign-off too, just this once.</p>
<h2 id="swap-out-mood-altering-words">Swap out mood-altering words</h2>
<p>Words like “problem” can feel large and frightening, particularly when people don’t realise they have one yet. Softer words that mean the same — like “issue” — are less likely to inflame. Instead of a confrontational:</p>
<p>“You need to fix your credit card problem.”</p>
<p>Try:</p>
<p>“There was an issue with the card.”</p>
<p>But better still to avoid both when you can:</p>
<p>“Please could you check your card details for us?”</p>
<p>This may feel like pointless semantics or thesaurus tennis, but it is interesting to see the difference small word switches make, especially in those who are naturally defensive of any perceived critique.</p>
<p>There is a danger here that you’ll start to refer to bigger incidents as “our little glitch” or “today’s whoopsie”. Don’t do that. The point is not to polish your turds, and you should be up-front about major issues using plain language — language like “network-wide downtime” and “the fire ant invasion in data centre three”. (And go ahead and blog pictures of the fire ants.) But for day-to-day support communication it’s fine to soften your language to appear calmer and more neutral.</p>
<h2 id="use-gender-neutral-pronouns">Use gender-neutral pronouns</h2>
<p>When writing documentation or reports, favour “they” over “he” or “she”. This has three purposes:</p>
<ul>
<li>It demonstrates respect and care.</li>
<li>It shows that you acknowledge diversity.</li>
<li>It saves you from having to play amateur sociologist and guess the sex of your customer by first name.</li>
</ul>
<h2 id="make-their-day">Make their day</h2>
<p>All of this distills down to one question that’s worth keeping in mind:</p>
<p>“Does my response make this person’s day better?”</p>
Teach the world to write great bug reports2018-02-14T00:00:00+00:002018-02-14T00:00:00+00:00https://www.nickcernis.com/blog/write-great-bug-reports/<p>“Teach the world to code!”, say the bootcamps and popular press. And so we should. But I propose a more modest goal in addition to training the next generation of <strike>bug-writers</strike> developers: let’s teach everyone to write good bug reports.</p>
<p>Software makes you feel superhuman one day, and then crappy and stupid the next. You should absolutely report the crappy stuff — it might even get better that way. But how do you condense your thought storm into a message another human can act on?</p>
<p>It helps to understand the people you’re writing to first. As a developer and technical writer happily embedded in a support team, allow me to help by senselessly lumping my co-workers into the same slightly-weird-fuzzy-creature basket.</p>
<h2 id="support-people-are-like-aardvarks">Support people are like aardvarks</h2>
<p>They are medium-sized, burrowing, nocturnal mammals with a hard skin as their primary means of defense. But not just that! The tips of their snouts are highly mobile and moved by modified mimetic muscles; muscles that evolved to sniff out your <em>questions</em>.</p>
<p>When I read a support ticket, I am trying to find a question or actionable statement. I need this because I want my reply to make you happy. So I scan your request with my super-snout for a question mark, read backwards from there, and then sniff out the rest of your message for ants and context and signs of insanity.</p>
<p>That means three things for you:</p>
<h2 id="three-rules-for-great-support-requests">Three rules for great support requests</h2>
<ol>
<li>Put your (single) question or bug outline in the subject. If you can’t put it in the subject use the <em>very first line of the email</em>.</li>
<li>Read the docs, FAQs, and known issues before asking or reporting.</li>
<li>Be nice. An aardvark may have a thick skin but it’s no armadillo.</li>
</ol>
<p>These guidelines apply whether you’re asking a how-to or pre-sales question, reporting a bug, or making a feature request. They also work for email, live text chat, phone calls, or maximum security issue containment facilities such as GitHub.</p>
<p>Here are some templates to help:</p>
<h2 id="a-bug-report-template">A bug report template</h2>
<blockquote>
<p>I found an issue with <code>[feature]</code>.</p>
<p>I am trying to…</p>
<p>What I expected to happen was…</p>
<p>What actually happens is…</p>
<p>When I take these steps the unexpected thing happens every time:</p>
<p>Here is a link to a screenshot, video, or public URL that demonstrates the bug:</p>
<p>I am using <code>[operating system] and [software version]</code> on a <code>[device name]</code>.</p>
<p>I think doing this might fix things:</p>
</blockquote>
<p>You may not be able to add all of those things, but aim for the full house. Your goal is to help the aardvarks reproduce the issue so they can fix or report it.</p>
<p>Remember the question-sniffing thing? Try to find the question or problem statement in this bug report (invented but similar to things I see):</p>
<p><strong>Bad:</strong></p>
<blockquote>
<p>My website is running a custom theme but the problem is also present if switching to a non-custom theme, so I think it’s a bug in your product and nothing to do with my code. Whenever comments are added to a post but there aren’t more than one of them and no custom modifications have been made, the page will show 1 comments. But in circumstances where multiple comments have been added the label is correct. I’m using a workaround at the moment but it seems to me that the label should be fixed automatically given that it works on other themes I’ve tried, which say 2 comments or 1 comment. I hope that makes sense.</p>
</blockquote>
<p>Pretty tough, right? With our bug template the same report becomes:</p>
<p><strong>Good:</strong></p>
<blockquote>
<p>I found a bug in how the comment count is displayed.</p>
<p>When there’s only one comment, the label shows “1 comments”, as pictured below. I expected it to say “1 comment”.</p>
<p>To reproduce this, leave one comment on a new post and look at the comment label. I tested this with an unmodified copy of Your Theme version 1.2.3.</p>
</blockquote>
<h2 id="a-feature-request-template">A feature request template</h2>
<blockquote>
<p>Please could you support <code>[feature]</code>?</p>
<p>I would use this every <code>[day|week|month|year]</code>.</p>
<p>It would make a big difference to how I feel about <code>[product name]</code> because <code>[your heartfelt appeal]</code>.</p>
</blockquote>
<p><strong>Bad:</strong></p>
<blockquote>
<p>I CAN’T BELIEVE your stupid product doesn’t implement quantum teleportation of transdimensional wonderquarks! It’s SUCH A SIMPLE THING it seems like it should be baked in by default. Who is running the ship there, anyway?</p>
<p>Like all my feature requests, this one is ABSOLUTELY BUSINESS-CRITICAL. Please get back to me urgently with a timeline of when this will be implemented. If you can’t do it just say so I can email your CEO with a similar rant then move to your competitor and write a long tweet storm about how dumb you all are.</p>
</blockquote>
<p><strong>Good:</strong></p>
<blockquote>
<p>Please could you support quantum teleportation?</p>
<p>I would use this daily to get rid of excess transdimensional wonderquarks.</p>
<p>The quarks are really backing up in our office, and I know it’s an issue many businesses face. You’re perfectly placed to help everyone on <em>this</em> Earth shift the quark problem onto someone else’s dimension.</p>
</blockquote>
<h2 id="a-how-do-i-template">A “how do I…” template</h2>
<blockquote>
<p>How do I fix the <code>[issue]</code> visible at <code>[url of page or image]</code>?</p>
<p>I am trying to…</p>
<p>So far I have taken these steps…</p>
</blockquote>
<p><strong>Bad:</strong></p>
<blockquote>
<p>I’ve been working on my landing page for three hours and it just isn’t working. The columns are all messed up and there’s too much white space above the image and half my text is in bold and honestly I’m thinking about giving up because this was supposed to be easy and it’s not.</p>
</blockquote>
<p><strong>Good:</strong></p>
<blockquote>
<p>How do I correct the layout issues on my landing page at <code>https://example.com/the-landing-page/</code>?</p>
<p>I am trying to:</p>
<ol>
<li>Make the content in the first section display in three columns instead of rows.</li>
<li>Reduce the white space above the image of the unicorn.</li>
<li>Make the paragraph starting, “Chocolate ice cream…” appear in normal text instead of bold.</li>
</ol>
<p>I tried to fix these issues for three hours by tweaking the dial marked, “autocorrect the bad things”, but would now love your help.</p>
</blockquote>
<h2 id="a-presales-template">A presales template</h2>
<blockquote>
<p>I am interested in <code>[full product name]</code>.</p>
<p>I read your full sales page at <code>https://example.com</code> and your FAQ page at <code>https://example.com/faq/</code>, but have three questions not covered there:</p>
</blockquote>
<p>It’s always worth reducing the number of pre-sales questions you ask unless the purchase is a major one. There are not many things you can buy on the internet that need more than three questions to determine whether they’ll be of use to you or not.</p>
<p><strong>Bad:</strong></p>
<blockquote>
<p>I’ve been thinking about buying from you but I need to know:</p>
<ol>
<li>What size battery does it take?</li>
<li>Will it stay that shiny or get kinda scuffed up easy?</li>
<li>Is the colour, like, <em>black-black</em> or just <em>kinda-black</em>?</li>
<li>You responses to questions four to seven will have no bearing on whether or not I buy your thing, but you know how when you start writing a list you sometimes find it hard to stop?</li>
<li>I wasn’t joking, was I?</li>
<li>Who would win in a fight between a lion and a monkey?</li>
<li>How about 10 monkeys?</li>
</ol>
</blockquote>
<p><strong>Good:</strong></p>
<blockquote>
<p>I’m writing about the Magic Jumping Shoes. I couldn’t find this information on your site:</p>
<ol>
<li>How many charge cycles are the batteries rated for?</li>
<li>Does your 30-second warranty apply outside the US?</li>
<li>I live in Canada and need the shoes to jump sleeping bears. Will they do that?</li>
</ol>
</blockquote>