Finding out there is something wrong with the work you did on a project is bad enough, but when reading through issues is like deciphering Latin, well it’s no wonder so many developers go postal. Writing detailed, thorough, and transparent issues should be the goal of everyone on your team, because we most often write issue request for someone other than ourselves. So let’s follow the Golden Rule of issue request, “Write issue request for others as you would like them written for you (or better).”
Writing good issue request, and teaching a team the same, will save everyone time, money, and confusion in the long run. It’s really a no-brainer. I’m talking specifically about Github, because I use it most of the time for code management and I know many other developers do as well, but what I cover can be applied to any issue management tool.
What An Issue Should Accomplish
When a person reviews an Issue Request there should be enough information that they have a good handle of what is being discussed, they don’t need to know or come up with a solution instantly, but nothing about the issue should be mystery meat.
The Perfect Problem
Writing the perfect issue probably isn’t possible, because we are all different and have subjective views on what makes sense or how a task should be handled. But we can create a general “good faith” guideline that if we all attempt to follow will make projects run smoothly, better our relationship with coworkers, and put a smile on your grumpy boss’s face. Let’s cover the basic anatomy of an Issue Request and how we can be awesome:
Relevant Subject Line. The subject should be specific but not lengthy. You have 40-60 characters to give a clear and concise summation of the issue. For more about writing subject lines, check out Microcontent: How to Write Headlines, Page Titles, and Subject Lines.
URL. Please, please, please, I’m begging you. If you make me wonder which page of a 1500 page website an issue is related to, I swear I will hunt you down and kick your puppy.
Full Description. The meat of an issue should describe in detail the specifics of a problem. Better to over-communicate than be vague. Be clear in your writing and re-read the content from someone else’s perspective, coming at it knowing nothing about the situation.
Bug reports require a more specialized attention to detail and procedure, I’m not going to cover that in detail here but do suggest reading Writing Bug Reports.
Situation. Once again over-communication is better than not mentioning specifics. Whether you believe it’s relevant or not listing the Browser, Operating System, on a Mobile device, in Incognito Mode, or has Javascript disabled could be relevant The more specific the better. I once had an issue from a customer that made zero sense until (after getting screenshots via email from him) I deduced he was using Incognito Mode, which wrecks havoc on Icon Fonts.
Screenshots. Screenshots are a developers best friend. If you can add a screenshot, do. It can’t hurt and may actually clarify. One thing, if there is an issue with a button at the bottom of the screen, take a shot of that one button and its surrounding area. Please don’t send a full desktop screenshot on your 27” iMac. P.S. Screenshots with annotated drawings and notes are awesome!
More. There are always more things you can do, such as tags. Each situation is unique and has its own challenges. Do what is best to fully and clearly describe an issue.
Shake Things Up
Let’s face it, capturing peoples attention is tough. And since we can’t hire a marketing firm to make our issue request more appealing we need to do the best we can with the tools at our disposal. Using simple styles highlights the most important aspects of an issue. Github makes this super simple to achieve with Github Flavored Markdown, and dang, they have a cheat-sheet button available! Thanks Github!
- Lists Are Awesome. List are easy for humans to parse through and organize information.
- Style Key Words. Don’t be afraid to italicize or bold words if it helps point out important aspects to note.
- Link the friggin’ URLs. If URLs are not automatically linked and I find out you didn’t link a URL, I swear I will hunt you down and kick your puppy!
What Not To Do
Well heck, this is the easy part.
- Assume the Solution. Unless you really know what the solution is, and you are expertly familiar with the situation, do not assume you know how to fix something and tell the Assignee what the problem is and how to fix it.
- Don’t Be Vague. “Something is wrong with the slider” is not a good description of the problem. Don’t assume someone can go look at something and automatically figure out exactly what was meant.
- Don’t Be A Puppy Kicker. Be Courteous. We can all be emotional beings, and being told we did something wrong can really stir the pot. So be kind and courteous, please. Remember the other Golden Rule, “Treat others the way that you want to be treated.”
A Little Bit More
While writing my thoughts I did a bit of research as well to see what others say about writing Issues. Two articles I found useful are How We Write Github Issues by Wiredcraft, and Github Issue Etiquette by Slava Akhmechet. Both make good points, some I agree with and some I don’t, but it’s up to each person individually (or team) to determine a method that makes sense and is helpful.
If you have questions or comments feel free to leave a note in the comment area below, or find me on Twitter at @calebsylvest.
. All Rights Reserved.