One of the sessions I enjoyed the most at API Days 2018 was Cristiano Betta’s talk on Developer Experience (DX), i.e. how to more effectively engage with developers who are consuming your API’s. The learnings go beyond developer onboarding specifically, and are applicable to product development in general – which is partially why it was so cool.
Slides here: https://betta.io/blog/2017/11/10/the-seven-sins-of-developer-experience
I also caught-up briefly with Cristiano afterwards where he expanded on a couple of points, as the talk he gave was a slightly shorter version of a longer talk.
An overarching theme was reducing cognitive load through the use of fundamental design principles. The deadly sins he covered were mainly around information:
- Too much
- Too soon
- Too little
- Unstructured
- Unsupported
- Incomplete
…with “no control” over tools as #7.
There was a variety of points of interest that I noted down, which I’ll briefly cover, but the things that really grabbed my interest were:
- “Too little / too late”, which is effectively about taking a holistic approach.
- The idea of measuring and responding to developer friction.
Note – the focus of Cristiano’s talk is around the developer experience in terms of on-boarding rather than the API design itself – for more info on that (developer experience in terms of API design) you might want to check out something like APIs You Won’t Hate.
Too Little, Too Late
This is partially about documentation – but not in the sense of manuals, it’s more about providing enough information when it is needed. Case in point: resolving errors.
The example Chistiano gave was when a developer is making a call to your API (probably the for the first time) and they encounter an error – e.g. related to input. Let us say they call your API which provides this response:
{
"error": "000123 - Invalid input"
}
What you want to avoid is the situation where the developer needs to resort to internet searching. Sure, you might have it covered in your help documentation:
Developer Guide – Error Codes – Page 421
Error 00123 – Invalid input. Occurs when you use a boolean on a Friday, on Friday you must use an int: 0 = false and 1 = true.
Your problem is that developers will already have formed familiar techniques for dealing with issues like this, probably using online resources – resources they are familiar with, and which through habit present them with a relatively low cognitive load.
There are many reasons why this is bad: you have no control over the experience, how long it will take and how frustrated they will get – not to forget “OMG, I can’t believe they don’t just say that” and “why is this so unnecessarily hard” comments all over StackOverflow.com.
What’s The solution?
A better way to do it is to include useful information in the responses error message itself:
{
"error": "000123 - Invalid input.
Occurs when you use a boolean on a Friday, on Friday
you must use an int: 0 = false and 1 = true."
}
Yes, you can also have this information in your developer guide. The trick is including the relevant information when it’s needed; not too much, not too little, and just at the right time. This leads on nicely to another cool concept…
Developer Friction
Adrian Trenaman’s QCon NY 2017 presentation on Developer Experience included the idea of minimising “the distance between ‘hello, world’ and production”. In that context he was discussing development in a holistic sense (tooling, environment, and so on) where you are employing developers, but as Cristiano explained to me, you can also look at “developer friction” in the context of developer adoption of your APIs.
In this context, developer friction is effectively the amount of time between (a) making an API call that errors and (b) the first successful call to the same API – or some meaningful variation along those lines, such as the time between developer registration and their first successful API call.
So, imagine that you have 10 developers a day signing up to your API and making their first ‘hello world’ call. Let’s say 50% of them get an error the very first time they make a an API call, and on average 90% of those developers are able to make a successful call within 2 minutes. Now compare that to a situation where 80% get an error the first time, and of those 90% take on average 2 hours to make a successful call. Clearly the second situation has much higher developer friction.
According to Cristiano, some organisations use techniques like this to monitor adoption of their APIs and specifically to help them identify areas where their overall developer experience may need improvement.
Other Gems
I won’t go into these concepts in much detail, and hopefully you should be at least aware of them already – if not I kindly (and strongly) suggest you check them out. Cristiano’s slide-deck is a great place to start. It covers a lot more than what I have included here.
Cognitive Load, Overload and Progressive Disclosure
Cognitive load refers to the effort being used in the working memory; cognitive overload is where (for example) a learner is unable to simultaneously process a certain amount of information or tasks. Solutions to this include:
- Chunking information up, e.g. into lists of about 8 items, with a useful heading.
- Applying the 80/20 rule, e.g. call out the small number (~20%) of items that developers are most likely going to be seeking, especially if they are new to your platform, and leave the other 80% accessible but through other navigational means.
That second point is an example of Progressive Disclosure, a great technique for managing cognitive load, covered in detail in the book “Universal Principles of Design”.
Another really interesting pitfall around cognitive load was around asking people question, like on sign-up forms:
As Cristiano explained, this may look simple but it raises a lot of questions in peoples heads – questions which might not seem a big deal to you but can be problematic for others (especially if it’s mandatory):
- Who will see this?
- Can I change it later?
- What do you need it for?
These 3 simple question really resonated with me, and they provide a simple checklist you should consider when reviewing questions you ask your customers. I know from firsthand experience that questions like this, in some circumstances, often force me to stop and think way more than should be necessary.
Tools Out of Control
This is where community tools and SDK’s are more obvious than yours. Unfortunately Cristiano didn’t have time to go into this in a lot of depth in terms of solutions, but clearly SDK’s and other tools are a integral part of your offering, and a critical part of DX; therefore it’s critical to have a plan in place for managing these as part of your product.
This is most likely going to include monitoring the community – where they are; understanding what tools they want; staying engaged.
Using Structure
Another nice 3 point list was around structure – i.e. allowing people to navigate through the information you provide them:
- Where am I?
- Where can I go?
- Where did I come from?
Telling a Story
Whilst having information in inherently useful structures is good, you can augment this in key situations (such as developer onboarding) with Story Telling – another technique covered in the Universal Principles of Design.
Cristiano cited Pusher as an example of doing this well – the “hello world” make your first app story. Here’s the screenshots, as you can see the path from account creation to “hello world” has been streamlined, and users can easily opt out of this if they want.
References
- https://betta.io – Cristiano’s website, which includes:
- https://www.apidays.com.au/
- Removing Friction in the Developer Experience: Adrian Trenaman Shares Experience from HBC at QCon NY (2017)
- Cognitive load (Wikipedia)
- Universal Principles of Design (Books)
#ApiDaysAU
Peruse Muse Infuse 