“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 bug-writers developers: let’s teach everyone to write good bug reports.
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?
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.
Support people are like aardvarks
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 questions.
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.
That means three things for you:
Three rules for great support requests
- Put your (single) question or bug outline in the subject. If you can’t put it in the subject use the very first line of the email.
- Read the docs, FAQs, and known issues before asking or reporting.
- Be nice. An aardvark may have a thick skin but it’s no armadillo.
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.
Here are some templates to help:
A bug report template
I found an issue with
[feature].I am trying to…
What I expected to happen was…
What actually happens is…
When I take these steps the unexpected thing happens every time:
Here is a link to a screenshot, video, or public URL that demonstrates the bug:
I am using
[operating system] and [software version]on a[device name].I think doing this might fix things:
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.
Remember the question-sniffing thing? Try to find the question or problem statement in this bug report (invented but similar to things I see):
Bad:
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.
Pretty tough, right? With our bug template the same report becomes:
Good:
I found a bug in how the comment count is displayed.
When there’s only one comment, the label shows “1 comments”, as pictured below. I expected it to say “1 comment”.
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.
A feature request template
Please could you support
[feature]?I would use this every
[day|week|month|year].It would make a big difference to how I feel about
[product name]because[your heartfelt appeal].
Bad:
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?
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.
Good:
Please could you support quantum teleportation?
I would use this daily to get rid of excess transdimensional wonderquarks.
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 this Earth shift the quark problem onto someone else’s dimension.
A “how do I…” template
How do I fix the
[issue]visible at[url of page or image]?I am trying to…
So far I have taken these steps…
Bad:
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.
Good:
How do I correct the layout issues on my landing page at
https://example.com/the-landing-page/?I am trying to:
- Make the content in the first section display in three columns instead of rows.
- Reduce the white space above the image of the unicorn.
- Make the paragraph starting, “Chocolate ice cream…” appear in normal text instead of bold.
I tried to fix these issues for three hours by tweaking the dial marked, “autocorrect the bad things”, but would now love your help.
A presales template
I am interested in
[full product name].I read your full sales page at
https://example.comand your FAQ page athttps://example.com/faq/, but have three questions not covered there:
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.
Bad:
I’ve been thinking about buying from you but I need to know:
- What size battery does it take?
- Will it stay that shiny or get kinda scuffed up easy?
- Is the colour, like, black-black or just kinda-black?
- 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?
- I wasn’t joking, was I?
- Who would win in a fight between a lion and a monkey?
- How about 10 monkeys?
Good:
I’m writing about the Magic Jumping Shoes. I couldn’t find this information on your site:
- How many charge cycles are the batteries rated for?
- Does your 30-second warranty apply outside the US?
- I live in Canada and need the shoes to jump sleeping bears. Will they do that?