Collecting feedback is the most crucial thing to keep in touch with your customers. You can provide separate email address for feedback. There’s nothing wrong with it. It is important that you start collecting feedback as early as possible and make it as easy as possible. Developers are quite familiar with Github and thus using that as a channel and backend for feedback is a no-brainer. We did a small experiment on that at Platform of Trust.
Part if bigger feedback system
Doing a simple free feedback channel for developers to make wishes regarding APIs is simple. We did a small experiment today at Platform of Trust. The described solution is part of a bigger platform wide feedback system, which I’m not going to explain here yet. Eventhough we use Github as a free backend for the feedback, we can easily pull the data from there automatically to where ever we want. Notification of new issues are automatically pushed to Slack.
We can use for example the Github API or Zapier. In our case we probably don’t pull the data away, but use Github issues as the preprocessing location and move issues from there deeper to development process (JIRA, Azure DevOps) is needed.
It is important to enable easy way to give feedback. As important is to think how you process the feedback so that it is used in future development. Third thing to consider is the communication towards to issuer and rest of the developer community. Using Github offers transparency since all can see the list of wishes and related discussion. If you would pull the feedback via email, it is likely that all feedback is hidden from all. Sometimes that is probably ok, but wee aim for transparency in all aspects.
API Documentation as starting point
Our Platform’s API documentation (for public APIs) is published via Github pages. The build process is in Travis and source files in Github (including the machine readable API spec files). I’m not going to discuss the whole build process but the feedback concept which you can replicate easily.
You need to create template for the wish in Github. Wish is something that is missing from our APIs. It might be also something that is missing from documentation as well. You could say it’s a missing feature which we have just renamed to wish. “Make a wish!” We do not guarantee that wishes come true, but we promise to consider your wishes.
In short the API docs contains “Did we miss something? Make a wish!” links next to API on the right column where you normally see our code examples. Our thinking is that the features (or wishes) come to your mind when looking at the examples. Thus the right most column.
Of course the links could be in the middle column as well. Nevertheless, links are on the right column now. Each link points to custom template in Github. Those are easy ro create. Each link passes some parameters to Github template. An example is:
- assignees is empty, but you could assing the issue directly to API designer or scrum master.
- template is name of the template to use (you created this)
- title is the issue title (leave empty is you wish)
- labels contains the name of API and additional “Wish”. These are converted into labels in Github. Notice that the label names are case-sensitive.
The result is like below if you paste the above link to browser (or click here):
The issue template name contains intentionally the word “pain”. Developer is having some issues with our APIs, they are experiencing pain. We need to find a remedy for that. In short we don’t expect the developer to tell us what is the fix. Instead we want them to describe the pain. That is why we have prefilled the content field with “# Describe the pain in using this API”. After that we would like to know how urgent or severe is the pain (“# Indicate the importance in number”). That’s it. Of course we can’t stop the developer from proving ideas for solution, but in our thinking that is not customer’s task or duty. We need to find the remedy as API provider.
The result in action
Setting up and testing all that took couple of hours including API docs generation engine code to inject correct links to wanted spots. When all that is put in action, it looks like this:
Some more to read from 100 Days DX
- #100 - The biggest open resource on Developer eXperience so far
- #99 - Hackers - the top 1% of engineers
- #98 - Invalid Open API spec files ruins the developer experience
- #97 - Lightweight API evaluation framework
- #96 - Embracing open source community driven tools development
- #95 - Exploring the multilevel nature of API Design Guides
While you are here...
Check out Platform of Trust in which I've worked to enable best possible developer experience!