Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Developer Experience (APIdays Mediterranea edition)

Developer Experience (APIdays Mediterranea edition)

UX research and design methodologies for API products. #DX

Presented at APIdays Mediterranea . Speaker notes below slides.


Jeremiah Lee

May 31, 2013


  1. Jeremiah Lee • APIdays Mediterranea • 2013-05-31

  2. #DX @Jeremiah @JeremiahLee

  3. The internet has been called The Information Superhighway, but information

    was just the first part of the internet's story. We’re now witnessing the idea of *division of labor* being applied via the internet. We're no longer limited to sharing information. Web service APIs have given us the ability to share our specialized capabilities with each other. And this means that not only can we do more, but that we can do more, more easily. I don't need to tell you—here at APIdays—about the benefits of using API products. What I would like to convince you of is the value in applying User Experience research and design methodologies to the API products you're responsible for. Because together, we can do so much. If we believe that building things together is the best use of our skills and time, it makes sense to help others help us.
  4. SOAP REST RESTful RESTish? XML JSON Hypermedia URI parameters OAuth

    1.0a OAuth 2.0 snake_case camelCase RPC What we usually talk about when we discuss improving our API is the actual design of the API. We debate the merits of RPC and SOAP and REST and Hypermedia design patterns, XML versus JSON, OAuth 1/2 or other authentication mechanisms, snake_case versus camelCase, URL parameters versus JSON objects. And while these are important conversations to have and while they do impact developer experience, an API is just an interface… a user interface. And UX is much more than just UI.
  5. SOAP REST RESTful RESTish? XML JSON Hypermedia URI parameters OAuth

  6. API

  7. Application Programming Interface

  8. Interface Application Programming User

  9. Interface User != UX

  10. Graph by Dave Corby (2010) based on Guide to the

    So ware Engineering Body of Knowledge (SWEBOK) by IEEE Computer Society (2004) Customer Requirements Requirements Specification Functional Specification Design Specification Validation Review Verification Study the requirements Clarify the requirements Write the so ware Test the so ware Validate against requirements Review with customer Define new requirements Software Development Life Cycle What sticks out to me most in this diagram is how much of software development is not programming. This (pointing to "write the software") is when the interface—the API—is critical to the experience. This (the rest of the diagram) is when it's not.
  11. FUNCTIONAL UX Hierarchy of Needs — Aarron Walter, Designing For

    Emotion When we look holistically at a solution to a problem, we're evaluating the quality of a solution on multiple levels. I think a translation of Maslow's Hierarchy of Needs is appropriate for this evaluation. The one I like to reference is by Aarron Walter from his book, Designing for Emotion. We start with *functional* — The API has to solve the problem it claims to solve. Simple enough. But let's think for a moment about why someone would choose to use an API instead of doing it themselves. Most APIs replace some existing known way of doing something, but they need to do it so much better in order to convince people to use them. For example, SendGrid not only replaces SMTP, it does SMTP better than you could ever do it yourself. They're experts at deliverability and keeping your email out of spam folders. So not only do they solve a problem, they solve a problem very well.
  12. RELIABLE Availability (uptime) Scalability (load, response time) Stability (consistency) Security

    FUNCTIONAL UX Hierarchy of Needs — Aarron Walter, Designing For Emotion But that functionality's existence is only as good as it's *reliability*. Reliability is really one of several non-functional requirements. availability (uptime), scalability (load and response time), stability (consistency), security. These -ilities don't matter if you don't provide the functionality, but no one is going to use an API if it can't be relied upon. Trust is important. Not only do you do what you say you will do, but you do so reliably.
  13. USABLE Intuitability Testability Corrective Guidance RELIABLE FUNCTIONAL UX Hierarchy of

    Needs — Aarron Walter, Designing For Emotion Moving up the pyramid, we get to *usability*. Usability is a special requirement because it takes several forms: - intuitability: This is how quickly and easily the functionality can be obtained. This is largely the design of the API. - testability: How easily can developers confirm their implementation is correct? - The last form is corrective guidance, aka error handling. This is especially important because some errors happen at implementation and some happen at runtime based on input. Whether it's the API's, the developer's, or the end user's fault, everyone is disappointed when an error happens. How an API handles errors and how you help developers handle errors so that a situation can be corrected is critical to usability.

    Walter, Designing For Emotion At the very top, we have *pleasurable* — This is the overall enjoyment and maximum value creation of the product. It's not just surprising and delighting your users, but solving a problem better than any other way. Using your API feels like the obvious solution to a problem at this stage. People are throwing money at you. ["TAKE MY MONEY!"] For me, I think of Twilio here. While I could run my own SMS gateway and work with telephone companies, I'd rather just let Twilio deal with it because they handle every detail of SMS much better than I ever could and they do it cost effectively. So looking at the pyramid: These bottom two rows are what convince a great developer there is a better way to do something they've done before. The next row is what convinces a developer to actually act because it's so easy to unlock the value proposition. The top row is when you've fulfilled the promise of division of labor 2.0. Your specialty has become someone else's super power. They are stronger even though they have an external dependency and willingly engage you. And again, API design is important—it's the majority of the usability layer—but it takes so much more than a well designed API to provide a great developer experience. Many of these elements above and below are invisible when perfect, but are sources of pain and confusion when imperfect. The only way you can identify and resolve these elements is by talking with your users.
  15. None
  16. Empathy as an Applied Science UX is empathy as an

    applied science. Breaking that down further: Empathy is the ability to understand, anticipate, and share the feelings of another person. And an applied science is the discipline of using knowledge gathered via the scientific method to solve practical problems.
  17. understand anticipate share feelings

  18. research in order to solve problems

  19. Empathy as an Applied Science Rephrased: it’s observing and learning

    about our users—their struggles and their motivations —and then applying that knowledge to make it easier for them to satisfy their desires by using our products. UX is a broad term that incorporates many disciplines, but ultimately, it is a research-driven approach to design.
  20. 5 Common Style of Design — Jared Spool, User Interface

    Engineering Research Costs Time Resources initial focus on complexity and ease of use developing for users beyond ourselves designing something we've never designed need to fill the gaps between activities Unintentional Self Genius Activity Focused Experienced Focused To quote them: "The order reflects the increasing amount of *research* the team employs to make decisions. While one could also think of the order as a growing maturity of the team, it turns out that each one has its place. Some projects don't warrant the costs, time, and resources necessary for extensive user research, but other projects will fail without it." The key word here is 'research'. What Jared Spool is saying is that in order to take an API from mediocre to awesome, we need to know more information about the people using the product to make informed decisions.
  21. Activity Focused Design • Each step should: 1. Affirm progress

    towards user's goal 2. Inform user of next step • User research reveals workflow context • Assumptions are dangerous: • Yours: blind to issues because of familiarity • Users': anti-pattern implementations
  22. "Not just discrete activities, but all the things that happen

    between activities." —UIE
  23. 5 Steps of User Research 1. Identify research method 2.

    Figure out who to interview 3. Conduct the research 4. Review findings 5. Act on the findings
  24. Methods of User Research • user interviews • contextual inquiries

    • questionnaires • focus groups • card sorting • eye tracking • click tracking • tree tests • journaling • shitty pair programmer
  25. Conduct the research • Inform user that they are not

    being tested • Ask user to think aloud as they work • Confirm that they consent to being recorded
  26. As they work... • How do they get started? Time

    from desire to first request. • How do they find and utilize documentation? • How do they discover where to register or update configuration settings with you. • What is their debugging process? What errors do they encounter and how do they diagnose and resolve them? • How do they verify that they have properly integrated the API? What causes them to feel confident to push to production?
  27. Other observations • Who made the decision to use your

    API? • Are you replacing or augmenting existing functionality? Are you a new feature? • What's their level of familiarity with the process that's being fulfilled? • What external resources outside do they need to complete the tasks with your API? • Are there interactions between the end users that you're uniquely facilitating for them?
  28. Rocket Surgery Made Easy: The Do-It-Yourself Guide to Finding and

    Fixing Usability Problems by Steven Krug
  29. Two more things... • Remember to follow up with test

    users, particularly when usage increases or decreases • Monitor support requests • Type (API bug, user bug, approach inquiry, etc) • Time to resolution • Stage of integration • Comprehension of API
  30. The secret to machines talking to machines is to speak

    human first.
  31. Gracias por asistir. Content available at http://dx.jeremiahlee.com Start simple. Dream

    big. Do good. Be well. Please support the Electronic Frontier Foundation