Why the techiest of projects still need to use user-centered design
Machine Box is a pretty techy project; it’s a series of Docker images containing machine learning APIs. The users are developers, who must write code to integrate the capabilities into their own projects.
All a developer really needs to get going are instructions for how to run the boxes, and some documentation explaining the ins and outs of the APIs.
Treat developers like visitors to an exclusive club
One of the first decisions we made at Machine Box was that we were going to put as much time and effort into the developer experience as the machine learning capabilities.
The feedback we’ve had has been overwhelming, so we wanted to share our approach in the hope of convincing others to do the same. It comes down to this:
Remember that a developer is a person; usually a weird person tells computers what to do, but still a person.
Artwork is more important than you think
It might seem like a luxury to create artwork for a tech project, but we have noticed that even open-source projects with a good logo get more respect, more interest and better engagement. This has something to do with developers being humans again. There seems to be an emotional connection with the project, rather than a purely logical one; but maybe not — either way, it works.
The process of engaging with a designer and coming up with project artwork is rewarding in itself for everybody involved, even if you can’t afford to pay them for it just yet.
Ashley McNamara is a Principle Technologist at Pivotal, a great creative artist and the juice behind https://gopherize.me, so was the perfect choice for creating a mascot for the project. Armed only with a very simple brief (one line), the first candidate we got back was Machina, and suddenly Machine Box felt like a real project.
Frictionless account creation
We wanted it to take less than a minute for someone to get going with Machine Box, but we had to get a secret key into their hands. We considered allowing people to sign in with their Google or GitHub accounts, but were pretty surprised by the amount of data you can collect on someone using this technique and we don’t want to collect personal data from our users like this.
The obvious alternative was to get them to create an account with their email address and password, but what if we could eliminate even the password?
Instead we opted for a Slack style “magic link” approach, where we ask only for their email address.
We send a special link that contains a secure (and time limited) token which people can use to sign in.
Yeah developers are smart… and lazy
Of course a smart developer can easily figure out how to set an environment variable and use the docker command to run one of the boxes (remembering to pass in the environment variable and expose the right port) but you know what, if it can be a click and a keypress, then why the hell not?
Clicking the little copy icon, opening a terminal and pressing Cmd+V (or Ctrl+V) means you can spin up a box on your local development machine in less than sixty seconds (it actually depends on your internet connection).
It also has the side-effect of showing users exactly what’s going on. We considered doing a curl | bash to make this even easier, but hiding things too much makes things feel too magic and you lose the opportunity to teach your users something.
After the latest image is downloaded, the Docker engine will run it and bind to the logs where the conversation continues:
After thanking the user for trying Machine Box (we genuinely do love people who like to play with things and see what they can builld) we point them to the console, which is now running on their localhost.
Ship with documentation and a playground
Using a web browser, going to the relevant port running on the localhost serves the interactive console for the box.
This isn’t hosted API documentation, it ships with the box which means it’s always the right version with the correct information, and is always easy to find.
Each section has web forms that let you use the APIs without writing a single line of code.
In the example to the left, you can teach Facebox new faces.
The extra effort (it wasn’t much actually) not only gave us the chance to use our own APIs to build something — and therefore gave us the opportunity to catch ugly or inelegant design traits — it allowed us to communicate with developers in a pretty unique and engaging way.
What next?
To see what the developer experience is like for yourself, take a little tour of Facebox where you’ll teach it who The Beatles are, and ask it to recognize them from a busy photograph.
You can contact Machine Box on Twitter, or through the website.
