I started to think about iterative & agile development. Those terms are tossed in the air by business people in conferences and meetings. You know, just stuff the sentence with technical sounding terms and all is solved. This reminded me of this comic strip

DX is about process and that’s why I try to discuss different parts of the DX or DX development process in the series. We see too much discussion of the results or goals, but not enough of the often bumpy road to it. As a reminder some of the differences of UX and DX according to Fagerholm and Münch

API and platform development is iterative just like developer experience. You are never done (unless company dies). You have new versions and you go on. How do know how to improve the API for example? One way is to analyse the usage and see how your customers try to use your API. You catch perhaps some patterns. Error situations are fruitful source of information in this. You customers do not know how to use your API. If you can spot the patterns causing errors yourself, that is good. You might even fix some documentation before anyone gives you feedback.

Offer a route to ventilate pains

But then your API might still be lacking some features or parameters. Those might make the usage more simple, more efficient or even enable new use case (more potential customers). How do you get that information? When do the developers (consumers) get the ideas which you should know? One obvious spot is the API documentation. You should see the API documentation as two way street. You don’t just shovel the information towards developers, but try to enable feedback as well. Now if you don’t express clearly that you want to have feedback, you will not get it. If you don’t make feedback easy, you don’t get it. Instead the feedback goes to Internet and messages to peers. In those cases the result often is not pretty.

As I said, API docs is a place where the details start to matter. Developer is looking for an efficient and robust solution to call your API. If they can’t find it, they might have ideas how it can be achieved. Even if they don’t know the solution, they for sure know the pain and can describe it

Tell me your pain points

I don’t so much want to know how the developer would like to see problem solved. I’m more interested about the pain and problem they have. Customer probably does not want to start solving our problems. Even if they do, they might be wasting their time in figuring out a solution for which we can craft a better solution in 5 minutes as a team since we know how the system works. Don’t get me wrong I value if someone wants to use their time in that.

But I value more if they can accurately describe the pain to me.

Third call to action

Combining all the above. I would like to see “I’m in pain! Help!” kind of buttons / call to actions in API documentation. We already have links to Stack Overflow to see what has been asked before. We have ready-made link to open Stack Overflow question with our tag in it in the API documentation. Those are next to each API endpoint.

What I want is one more call to action there. Tell us your pain points! I don’t want the button to have lame “Feedback” text. I want something that creates emotional response and might even make you smile.

Pass parameters to template in Github

That button can take the developer to Github. Directly to issue template created for the purpose. Pass some parameters in the link and you can add the API name in the labels. Template contains the prefilled content.

https://github.com/PlatformOfTrust/docs/issues/new?
labels=Identity-API
&template=i-m-in-pain--here-s-the-symptoms.md
&title=Pain+points

In this case I want developer to tell me two things:

That’s it. Nothing more. When the developer arrives to the issue, it looks like below.

Now we get the pain points in Github. Those are notified to our Slack so that we all see what’s coming. The API designer can take issues from the list and evaluate if it’s a breaking change or not. Then make a task about it in our internal use only JIRA. At this point designer also reflects the issue with existing issues to see if there’s a bigger pattern or it is related to something on the table already. Eventually designer pulls suitable amount of tasks for 2 week sprint and does the design.

From there is goes to implementation, testing and release. Eventually issue in Github is closed and all customers are notified of the new features. You know the drill already. Now we have iterative customer need driven development going on.

Some more to read from 100 Days DX