DEVREL.net Breaking down APIs for better developer experience
November 24, 2017
Cristiano Betta is a cross-continental DevRelCon veteran, having spoken at previous events in London, Tokyo and San Francisco. At DevRelCon London this December, in an experiment that he calls “educational, entertaining, and potentially dangerous” (like all the best conference sessions) he’ll be conducting a live ‘API teardown’ – selecting an API at random and attempting to make a first integration by the end of the session.
Forensic API analysis is a core part of Cristiano’s consultancy work. He helps companies to improve their developer experience by auditing what they have already and then offering actions that will help them improve. “All the way from a developer first interacting with a product to that developer being live and successful on that platform. And I show them where their problems and pitfalls are.”
As well as identifying issues, Cristiano will offer actionable suggestions; “Then for improvements, sometimes it’s relatively quick fixes but it can also require re-architecting parts of their system to provide them with a better foundation on which to build their developer experience.”
And it’s not just about the whether something is factually correct or a particular endpoint gives the expected response. Often, it’s about lack of polish. Some companies that have spent a good deal of time and effort on the marketing side neglect the design and usability of their documentation.
“That’s often disappointing, because developers, just like business and marketing people, are influenced by the design of a page. Good design can help sell a product, and that doesn’t just apply to the marketing flyer or brochure part of the developer experience, but also to where the people are actually interacting with the product. So, one of the things I often tell people is to put a designer on their product and make sure that things are readable, approachable, and modern”
Ensuring that all the materials your company is putting out speak the same language is just as important as a common design touch. Cristiano notes, “There’s a certain benefit to having the same terminology definitely across the site, especially if you’re dealing with a rather complicated technology where you feel like you have to educate people about the jargon used in the industry. Because of this complexity, you can’t just brush it away and ignore it. You have to teach people, so you need to make that part of the process.”
You also need to be cognizant of the kind of person who will be most likely looking at a page, and creating content reflects that user. “So, if you’re talking to somebody who’s really just trying to understand what your product does and how it works, the story you tell them is very different than the story for the person who is committed, ready to go, has their API keys, their credentials, and really just wants to figure out this one specific kind of parameter. Then you don’t want to give them a lot of fluff and images. Instead, you just want to get them to the content that they want at that point. And that is, to me, is the tricky bit most of the time – making sure that people can understand what their target audience is for each bit of content.”
Of course, it’s not always easy to predict exactly who might be looking at a page – or how they’ll be lead there. Strong information architecture is the easiest way to make sure that developers are looking at things that cater to their level of experience – or can easily find them when they are led astray.
There are some classic ways you can help your users in this respect. “It’s stuff that we’ve been doing for years in most kind of modern websites. It’s things like having clear navigation, highlighting content to show where you are within the structure of a website – those kinds of things. It’s about sign-posting where a user can go and clearly saying where they are and giving them the option to step away towards where they need to.”
When architecting specifically for developer experience, Cristiano says you need to understand what kind of developers you might find coming to your site, and that you are providing clearly defined kinds of documentation and onboarding experience for them. “If you don’t do that, then it becomes a very muddled kind of picture. Somebody might land on a page and ask – ‘Is this content for somebody who’s already signed up, who’s already ready to go, who’s already got their credentials? If so, how do I find my way to the ‘get started’ tutorial? Where do I sign up?’ Those are just very typical questions that developers have as they try to use a product. And quite often, companies struggle with that.”
There are two main things Cristiano advises doing to make sure you’re on track. One is to make sure you’re following common best practices; “I’ve built up a database of a lot of the best practices. And what I mainly do with companies is that they hire me to come in and look at those best practices and tell them, ‘Look, these are the ones you’re doing well. These are the ones you’re not doing well.’ And that has the benefit that you only need to talk to one person.”
This will help you knock the really obvious things off your list. Then it’s time for the user research part. “For the not-so-obvious things, you can run an exercise with developers, a user experience lab. And I swear, if you run it with five people, any five people, you’re already going get valuable feedback out of that. The question with any kind of user research is, what are the questions you’re trying to answer? If you’re just trying to see what are the next things are you should be looking at, and where the problems are that need solving, then grab five people, sit them down, record them, see how they use your product, and write down the common problems, and then go fix them.”
For more complicated questions, Cristiano advises being a little more specific about the kind of developers in your pool. “Are these the right kind of people using our product?” Or, if not, what exactly is stopping these kinds of users from committing to paying for our product? That’s something you’re not necessarily going to achieve with five people.” Market research is an essential tool for helping to pick out what your exact segmentation of developers should look like.
Developer experience isn’t an inherently simple thing to get right (hence the growing market demand for experts in the field), and in the thick of designing and building an API, product managers will often lose sight of what it will like for the intended audience. In his talk, far from mocking whichever API he happens to pick in his talk, Cristiano hopes to demonstrate just how hard it is to push out something that works perfectly for every user – and, sometimes, how easy it is to do things better.
Join Cristiano at DevRelCon London 2017 on December 6th.
DevRelCon London speaker Tristan Sokol shares his ideas for making Stack Overflow a destination of choice for your community.
Convincing the company ‘suits’ to take APIs seriously as a commodity can be tricky – but get your strategy right, argues DevRelCon London speaker Mark Boyd, and the benefits could carry across your business.
Better documentation equals better developer experience – Adam Butler explains how his team at Nexmo are making this a reality.