35. How do I use it?
How do I learn how to use it?
Do I enjoy using it?
36. How do I learn how to use it?
Documentation
Comprehensive Easy to Navigate
Reference & Guide Easy to Search
Running Code Feedback Loop
37. Documentation
should be Comprehensive
Every method, parameter, return value, defaults,
implementation notes, errors, side effects, deprecation notices.
When in doubt, document.
43. Do I enjoy using it?
API Design
Familiarity Compatibility
Simplicity Debuggability
44. API Design: HTTP
Familiarity Compatibility
Use standards Support both
(when it makes sense) JSON & XML.
REST, RPC, OAuth.
Simplicity Debuggability
Don’t throttle. Give meaningful
error messages.
Most importantly: Never ever use SOAP.
52. Usability Testing
Did you complete the task?
How hard was it?
Would you recommend this API?
What would have made the
experience of using the API better?
Whose API does it better than we do?
AT&T Usability Testing
59. CONSUMERS
Thanks!
It’d be great if you
changed X.
I’d use it more if it
had feature Y.
Thanks - look what
I made with it!
60. The Developer Experience
IT MATTERS
LETS MAKE IT NOT SUCK
for more...
developerexperience.org developer-support-handbook.org
@pamelafox
Editor's Notes
Hey everyone! It’s great to be here in New Zealand speaking to you guys - I’ve attended enough NZ conferences in the past to know the developers here are really top-notch. I’m also honored to be presenting first thing in the morning, but to tell the truth, I’m also a bit nervous that you all will fall asleep on me. I’ve devised a clever plan however - I’m going to teach you a dance. I’ve been practicing it in the hotel room, and I think it should be the official dance of WDCNZ. Okay, now, everyone stand up. Alright, this dance is to the tune of YMCA. First we do the W, D, C, N - this one’s tricky, then Z. Okay then we put it together with the melody. WDCNZ! dododood WDCNZ! Okay, good job everyone! I’m pretty sure you’re awake now, so you can sit down. From now on, that will also be our secret code dance, in case we meet outside the conference and want to confirm we’re in the WDCNZ cult. ALright back to the topic at hand: Developer Experience. Today I’m going to talk about what it is, why it matters, and how to make it good- or in more technical terms, how to make it not suck.
Developer Experience is a new term that doesn’t get used much, so let’s start with discussing a term you probably hear all the time: user experience. There’s lots of fancy definitions for it, but it’s basically the experience that somebody goes through when using a product, and when we hear it, it’s usually in terms of a website user.
There are lots of websites out there, but for many of them, the experience can be broken into these stages - discovery, deciding whether to use it, signing up, getting started, actually using it continually, and getting help when something goes wrong.
For a concrete example, let’s look at the website for MailChimp. Have any of you used MailChimp? I actually hadn’t used it before last week and had no idea what it did, but I kept hearing that it had a great user experience, so I signed up just to check it out. (That’s a sign of a reallly good UX). When I first visit the site, I’m greeted with a huge adorable mail chimpanzee (bonus points because I love monkeys), a giant headline that tells me what it does, and an enticing button to sign up for free. So I continue on.
Then I go to the signup screen, expecting a long form, and all I have to do is enter my email username and password, and I get nice confirmations along the way that I’ve entered everything correctly.
Once I respond to an email confirming that address, I fill out a longer form. Okay, not as great, but atleast the form tells me along the way why it needs each bit of information.
After that, I’m brought to the user home screen and immediately see a step-by-step guide to getting started. I don’t have to search around, I know my first step: create a subscriber list.
Once I’m done that and want to explore other features, I get directed to watch videos explaining how the other features work. Oh, and along the way, the monkey at the top says stuff..like right now, he’s not wearing any pants. This gets better and better.
When I do have a question, I can search help at the top, see forum questions, live chat, or email, whatever works for me. Certainly there are other aspects of the MailChimp experience, but that gives you a good idea for what it’d be like to be a MailChimp user -pretty good, from what I can tell. But, I’m not an expert in user experience, and that’s not what we’re here to talk about.
We’re here to talk about developer experience. We can make up fancy definitions for DX as well, but really, it’s just user experience in the developer realm - the experience of a developer trying to use a tool, library, or API. And actually, we can break DX down into the same stages.
For an example, we can look at Twilio, a dev tool known for a good experience. Anyone use it? When I first visit, I see a landing page a lot like MailChimp - cute relevant graphics (unfortunately no monkey), a big headline that explains what it does, and a signup for free button.
Signup is easy, and it tells me more features along the way.
I’m immediately greeted by a get started guide - which involves actually calling a phone number which sounds pretty fun.
Once I get past the hello monkeys, I can browse through their examples or API reference to do what I actually want to get done.
And if I run into any problems, I can post in the forum or contact Twilio directly.
so that’s one example of a positive developer experience before we talk in detail about what makes a good experience, i first want to make sure you actually care about making a good experience. to do that, i need to understand who you are, before figuring that out, i have to figure out who you are
When it comes to developer experience there are providers - the people who create the experience and provide the library, tool, or API - and there are consumers - the people who use that product. To give you examples of people you already know, I checked out the speakers list. James Pearce works for Sencha as a developer evangelist for their platform, so he is very much on the provider side. Karl Van Randow creates iPhone apps using the Apple platform, so he is more of a consumer. Of course, many developers are in the middle - often when you’re doing it right, you also consume the tool you provide. Paul Irish uses HTML5 to create websites, but he now also works for Google Developer Relations, working with the Chrome team and teaching other people how to use it. Now what about you guys? Let’s start with the easy question: how many of you are consumers? Hopefully all of you. How many of you are providers? That might mean you work for a developer facing product, but also could mean you work on an internal API for your company, or you are an open source maintainer in your free time.
java - API - dad told me, dont ask him, look online. probably my first developer experience. university - started playing around with APIs. made a whopping $30 off amazon API, whee! so i cared because i was paid to do it but also because i started off as a developer, knew id be a developer in the future, and just wanted for developers what i would have wanted. but maybe you need more of a reason than that..especially if youre spending money on making a developer experience.
For a consumer, obviously you want a good experience. But why does a provider care? aka why should you care facebook example (tried using it, dreaded it, phasing it out) everyone in survey hated it if google+ succeeds and has a good API, developers more willing to leave. facebook has social graph API..buttt if it loses that..
developers will want to stay with it and get others to use it too - crowd-sourced advocacy effort. they’ll also use it for fun, even when they don’t have to, and come up with really cool things. maps API..used it whenever i had the chance. developers did more with it than we ever imagined, and got great publicity out of the out there ones. there are competitors but..
This question breaks down into a few questions. first question is one everyone asks- can this API help me accomplish what i want to do? to figure that out they need to understand the API feature set- if the docs are public (as they should be), they can read theirs, see the method they need and move on. even better, if there’s an interactive explorer, they can see for themselves the code that will do what they want- seeing IS believing! and then anyone who’s not just using a tool for shits and giggles will actually care if they can legally use it and afford it. they want to know the licensing, pricing. they want to feel it’s stable - dont want to build a business on top of something that will change or go away, especially if its not open source. they also want to think the team is committed to keeping it, so a general degree of polish and professionalism can help with it. something that can help answer both these questions are case studies -case studies show how a 3rd party developer has used something, and also prove that another developer trusts the tool enough to build on top of it. if you’re trying to attract non-hobbyist developers, case studies can be very useful. they also showcase the kind of apps you’re expecting developers to build.
This question breaks down into a few questions. first question is one everyone asks- can this API help me accomplish what i want to do? to figure that out they need to understand the API feature set- if the docs are public (as they should be), they can read theirs, see the method they need and move on. even better, if there’s an interactive explorer, they can see for themselves the code that will do what they want- seeing IS believing! and then anyone who’s not just using a tool for shits and giggles will actually care if they can legally use it and afford it. they want to know the licensing, pricing. they want to feel it’s stable - dont want to build a business on top of something that will change or go away, especially if its not open source. they also want to think the team is committed to keeping it, so a general degree of polish and professionalism can help with it. something that can help answer both these questions are case studies -case studies show how a 3rd party developer has used something, and also prove that another developer trusts the tool enough to build on top of it. if you’re trying to attract non-hobbyist developers, case studies can be very useful. they also showcase the kind of apps you’re expecting developers to build.
and then anyone who’s not just using a tool for shits and giggles will actually care if they can legally use it and afford it. they want to know the licensing, pricing. they want to feel it’s stable - dont want to build a business on top of something that will change or go away, especially if its not open source. they also want to think the team is committed to keeping it, so a general degree of polish and professionalism can help with it.
something that can help answer both these questions are case studies -case studies show how a 3rd party developer has used something, and also prove that another developer trusts the tool enough to build on top of it. if you’re trying to attract non-hobbyist developers, case studies can be very useful. they also showcase the kind of apps you’re expecting developers to build.
automated key signup. maps API - multiple domains - wont name names, but one i had to fill out a form, wait 3 days, and then got emailed with the addresses all CCed. dont make developers wait.
For each language, environment, and IDE. Common dev environments - mac linux yes even windows, with customized launcher utilities for each of them. PLus, some languages are associated with IDEs- like java and eclipse - so they also provide an eclipse plugin. Developers dont want to spend their time setting your thing up, they want to spend it actually using it. If it takes too long before they get their first whoa moment, then you might be discarded.
If it’s an HTTP library, provide client libraries for each language. Yes, they can construct the HTTP requests themselves, but particularly if there’s anything sort of authentication involved, it’s much easier if they can use a library. And make them open-source so they can just see how the library does it and adapt it to their needs. You don’t have to write all the client libraries yourself - you can encourage 3rd party developers to do it, and link to them. Just be careful about deprecations and upgrades.
Some people hate on hello worlds, but here’s the thing: humans like to see output. It makes us feel good, and motivates us to keep going. If we can follow a tutorial that will get us running with our first project that uses something- even if it’s simple- that will give us the confidence to keep going. Not everyone will use them, but you should always have a getting started tutorial that will step explicitly through the basics. Bonus points if they can then base their actual code on the starter code. PhoneGap provides a tutorial for each environment.
Once you actually get something minimal running, you want to figure out how to use it to accomplish your actual goal - which is probably more complicated. At this point, developers will look for documentation to learn about the interface for the tool or API.
first rule of documentation is to have it be thorough. if something isn’t documented, it basically doesn’t exist. even if your documentation has to say this is buggy, document it. better that you document what you know than have developers out there each spending hours to figure it out.
first rule of documentation is to have it be thorough. if something isn’t documented, it basically doesn’t exist. even if your documentation has to say this is buggy, document it. better that you document what you know than have developers out there each spending hours to figure it out. methods, params, error codes, defaults, return values
dev guide, reference, videos - both narrative and technical breakdown. people learn in different ways.
in the reference, every class/method comes with example code below the definition, and sometimes that code can even be run in the browser. (Or for HTTP APIs, sample request and responses in every data format are offered). hicharts atleast one example jsfiddle for every option, which is both runnable and editable. and they have 100s of options. its made it a lot easier for me to use their API over the past few weeks, cuz i can test stuff out without touching my code and figure out what option i need.
Good documentation also has several features - they may seem obvious but they’re suprisingly rare to find them all. Easy to find, subnav, different versions. Everything has its own page, so it can be found, linked to, and searched for online. table of contents, so people who are link to individual pages find everything. Not intimidating, even for newbies.
Search for methods, search for methods inside a class. Also needs normal SEO - many people will try to search in google.com. It’s popular like that. So don’t mistake of a purely AJAX accessible doc set.
Search for methods, search for methods inside a class. Also needs normal SEO - many people will try to search in google.com. It’s popular like that. So don’t mistake of a purely AJAX accessible doc set.
first rule of documentation is to have it be thorough. if something isn’t documented, it basically doesn’t exist. even if your documentation has to say this is buggy, document it. better that you document what you know than have developers out there each spending hours to figure it out.
So now that I’ve filled your head with ideas on what makes a good developer experience (and doesn’t), what can you do with that information?
simple! easy to use..low barrier..tho maybe not tooo low.
simple! easy to use..low barrier..tho maybe not tooo low.
So now that I’ve filled your head with ideas on what makes a good developer experience (and doesn’t), what can you do with that information?
So now that I’ve filled your head with ideas on what makes a good developer experience (and doesn’t), what can you do with that information?
simple! easy to use..low barrier..tho maybe not tooo low.
simple! easy to use..low barrier..tho maybe not tooo low.
So now that I’ve filled your head with ideas on what makes a good developer experience (and doesn’t), what can you do with that information?
you have to care/love/give a shit - be attuned to what they need, serve maps api: stayed awake with adrenalin maps api: woke up in morning thinking of devs maybe thats extreme but the point is this- if you dont genuinely care, it will be hard for you to know how to make it better. Maps API - support, features, new API Wave API - new API (both features + design - the common things were too hard, some things weren't possible at all), then docs, then we got killed
you guys also need to care-care enough about what youre using to want it to be better even if youve made it better for just 5 other developers, thats a good thing.
developer experience is a unique subset of user experience that deserves attention, providing a positive experience is something everyone should strive for for the bettermint of developerkind. Everyone’s experience is different though, so I’d love to hear about yours - chat with me in the hallways or online. Thanks and have a great day at WDCNZ!