Photo above from the US National Archives by Lynther Scott Eiler: motorist waits while an employee of an auto emission inspection station in downtown Cincinnati tries to locate why the vehicle failed its inspection, September 1975.To help with this, we are laying out some new guidelines for new feature requests, feature change requests and bug reports to make sure we’re getting the story straight from the start. We’re going to use them within our team, but we also hope that if you’re an Akvo partner you will use them as well.
First, we’re trying to move most of our feature-related and all of our code-related communication into our Github repositories where appropriate. Github is the distributed version control system that we use to allow us all to collaborate together on software development. Essentially, once we have the user story straight on what’s being requested (more on that later), we want to hold the conversation directly in the issues database for each product, so that everyone working on it or interested can see the whole thread and evolution, instead of these living in peoples’ minds or inboxes.
Second, we are being clear up front about what needs to be in a feature request or bug report, so that we can get the information we need as efficiently as possible to move the conversation forward. There are three broad categories we group our product feedback into: new feature requests, feature change requests and bug reports. Below are some general guidelines for communicating about each one. These guidelines are meant as conversation starters that document the request or problem, so that the person or team meant to act on it has a clear picture of what the user is looking for.
New Feature Requests
New feature requests for RSR and FLOW should come in as user stories. A user story is a few sentences written in everyday language that describes who the user is, what they want to be able to do, and why they want to be able to do it, for example: “As a FLOW admin-level user, I want to be able to limit access to certain survey groups on my Dashboard, so that I can make sure those surveys aren’t changed by people that aren’t in my project. This will help the FLOW Dashboard function better in my partner consortium.” The point of user stories is to make the user’s goals really clear to the software developer who will work on the feature. User stories should be short, easily understandable, and avoid suggesting how a feature should be implemented, and instead focus on what the user wants to be able to do. You’ll find detailed guidelines for writing and submitting user stories for RSR and FLOW over on our help site.
Feature Change Requests
These requests apply to a desire to change a feature that already exists in the product, whether it’s a defect (i.e. a bad design decision) or an enhancement (i.e. it works, but it would be better if it worked this way). These can get caught a bit between a new feature request and a bug report, but what matters is getting the description right, so when in doubt, write a user story and don’t worry too much about how you classify it. If you want to geek out a bit on the semantics and politics of a bug report vs a feature request, check out this post from Joel Atwood, co-founder of Stack Overflow, from his blog, Coding Horror.
Writing a good bug report is all about communicating to support staff and developers exactly what you are seeing in the software, so that they can quickly understand what’s happening and decide on a resolution. If your bug report is clearly written and easy to take action on, there’s a greater chance it will be fixed, and quickly.
Photo by Hash MilhanThe first thing the person reading your bug report is going to do is to try and reproduce the problem so they can see it for themselves. So your goal in your bug report is to make this as easy as possible. Bugs that can’t be reproduced are very hard to diagnose and fix. (Suddenly I can identify with car mechanics all over the world.) We’ve written some guidelines for bug reporting over on our help site. There is no need to be too wordy, but more specific detail is always better (i.e. “https://akvo.org displays a 404 error in my Chrome browser” is much more helpful than “This link won’t load”). As an example, the email below required several rounds of communication before we could understand what was going on from a remote location.
Email from panicked user: “Help, my FLOW dashboard won’t load! I’m about to start a training in an hour in Bangladesh, can you help?”
In order to figure this one out, we first had to ask a lot of follow up questions with hours of time zone delay, which was a frustrating experience for everyone. We’d like to guide our field staff and users to something closer to this:
Email from somewhat panicked but informed and level-headed user:
“From my training location in Bangladesh, when I type in my FLOW Dashboard URL (https://training.akvoflow.org/admin) and press enter in the Firefox browser I expect to see my Dashboard home screen, but instead a blank white screen loads inside the browser window, and refreshing the page or restarting the browser doesn’t change anything. I’ve attached a screenshot of what I’m seeing.”
Of course, do also say “I’m about to start a training in an hour, can you help?” Taking a few minutes to collect your thoughts and communicate the details of the situation will probably result in faster resolution of your issue.
All partner support requests or suggestions can come through our dedicated support sites, flowhelp.akvo.org and rsrhelp.akvo.org. From here, we’ll communicate with you about your issue, and move it into Github if it requires code changes. If you have a more general question, feel free to submit to one or the other and we’ll make sure it finds the right person.
Caetie Ofiesh is product manager for Akvo FLOW