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:

https://github.com/PlatformOfTrust/docs/issues/new?assignees=&template=i-m-in-pain--here-s-the-symptoms.md&title=Customer+wish&labels=identity-api,Wish

In there:

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