The ability to break down complex interactions into simple, delightful user experiences is an indispensable asset and competitive edge in software. These days, UX designers are among the first hires at a startup. UX for browser interface is quite an important subject, and there is a lot of material out there for someone interested building a career in the field. I enjoy reading Joel Califa’s blog, one my favorites. But, what if the product is a dev tool, SDK or an API? What if the place of interaction is a terminal or an IDE? What about UX for developers?
If you believe in the software-is-eating-the-world paradigm, then your competitiveness is a function of your software development velocity. In this scenario, developer productivity is the most critical resource for a company. Hence, it is imperative that we talk a lot about user experience for a developer or Developer Experience (DX). “Code” is not just a set of instructions for the computer, humans too consume it and collaborate with each other to maintain it and build on.
Side Note: DX in this post refers to the use of “code,” i.e., API, SDK, service or tool to build software applications. Why make this explicit assertion? Well, because there is a trend of UI-based drag-and-drop interfaces, which in my view transform a DX problem into a UX problem. Unfortunately, this does not work well in all cases. UI-based approaches tend to lower the entry barrier for new developers, but in a long-run, the experience may deteriorate (graphs become too complicated and confusing to debug).
What is Developer Experience (DX)?
DX is more perception or feel; it is defined as the sum of all the experiences a developer has while using your API, SDK, service or tool (API henceforth). Be it ease of using core API itself, documentation, recovering from errors or time to deploy. If any of these interactions are poor and painful, then it is considered to have lousy developer experience. There is very little chance that the developer will return or even mention this tool to anyone in her network.
DX is tricky because it lies at the intersection of design and programming. Unlike in the case of UX, there are no professionals who do DX. It’s up to the developers themselves. But UX in developer tools is mostly ignored.
Why is DX ignored?
Francois Chollet puts it down to what he calls an “empathic distance.” Developers rarely think of future users while building APIs. No one does a usability study for APIs. Problems surface only after friends and colleagues have struggled with the API and given up.
In most cases, developers assume that the future users will have the same context and experience as they do; this is not the case. Another significant trend is treating “difficulty” as a badge of honor (i.e., to say I can do this complicated stuff!). Working with hostile tools is time-consuming and takes a long time to learn, somehow this is considered good! I’ve also seen engineers shy away from automation and abstraction. Why? Because it shaves-off development time. Funny! But all this needs to change soon.
Empathy in DX
I’ve read some blogs and articles on good API design. Everyone seems to focus on higher-level concepts such as the importance of functionality, usability, and experience. While this is good, we need more lower-level details on what does this mean? I found my answer on the same blog by Francois Chollet (referred above), there three simple rules:
- Deliberately design end-to-end user workflows
- Reduce cognitive load for your users
- Provide helpful feedback to your users
The three simple rules are a simple, but a fantastic piece of advice for every API designer. In here, I see the first seed of “design thinking” in API design. Developers need to cultivate a culture design in their workflow. It’s important to always think about the end user (not just themselves). Keep empathy at the core. Thoughtfully designed APIs not only reduce the entry barriers for developers but also fasten the time-to-market for the software.
API design at rorodata
We at rorodata, are building a Platform-as-a-Service designed for data scientists. We abstract and automate all the complex software engineering and devops and provide data scientists with simple APIs that allow them to prototype, build, deploy and monitor machine learning models in production.
As our core offering is an API, we spend a lot of time working on our DX. Anand Chitipothu, our resident wiz leads the charge.
Side Note: Notes from Anand’s Beautiful RESTful APIs workshop in Bangalore
Our philosophy for DX is very much along the lines of Three Simple Rules put down by Francois Chollet. I will not bore you with more preachy stuff, but introduce you the process we follow to design and release our API.
Step 1: Module design
We always an entire module and cover it end-to-end. We start with simple block diagram on a whiteboard/PowerPoint and list down all the states, actions and results. We refine the list after multiple rounds of discussions with potential users.
Tools used: Keynote,PowerPoint
Step 2: Mock API Documentation
We then transform the interactions into mock API documentation, which contains the following:
- Usage i.e. what will the API look like
- Input parameters
- Output parameters
- Potential errors
- Edge cases and
- Supported data formats (if applicable)
We take special care to ensure that naming convention is consistent with the module and similar to something users may have used in the past. We share the documentation internally on our engineering blog; the team is invited to comment and share views.
Side Note: It‘s a good idea to present some of the early API ideas to the broader audience either at local meetups or conferences. We’ve tried and done it when we can, our talks at FifthElephant, PyData Delhi and PyCon UK.
The entire team does a walkthrough of the documentation and logs issues, if any. The documentation is refined and ready for prototyping.
Tools used: Wordpress blog, Slack Post
Step 3: Prototype, test and refine
The v1 of the module APIs are implemented and shared with the team. We dog-food the APIs and discuss the problems. The APIs are refined and tested again. We share the API with a set of external users and incorporate their feedback.
Step 4: Release
Once all the tests are complete, the API is released and made part of the platform toolbelt. Of course, there is continuous testing and update beyond this point.
We repeat these steps for feature changes or new additions. We try to benchmark our API with some of the best we’ve used in the past. Our objective everytime is getting the user from 0 to 1 instantly every time they use our API.
One of the best DX we’ve come across Heroku and more recently now.sh
Our platform and UI-dashboard which is used to monitor all the actions in one place. The dashboard is more a companion interface for the CLI tool.
Side Note: We follow a similar process for our UI design. Some of the tools we use are Keynote, Balsamiq, Mockdown-as-a-Service on our own platform. We prefer real interactive mockups instead of static ones.
We are just getting started. There is a long way to go for us. I’m sure you will notice many rough edges in the DX, and we’re working on ironing those out.
If you have a thing for good API design and would like to build elegantly designed dev tools (for data scientists :)), then we would love to hear from you. Of course, we’re hiring for engineering roles, more here. Get in touch to know more.
Author: Raghavendra Badaskar
Please do write to us with your views and comments. If you are a company/startup looking for help with machine learning, we’d be more than happy to help. Just drop us a line and we’ll get back.
Thanks Anand Chitipothu for the review, feedback and discussions on the topic.
