Developer eXperience design

TL;DR Sharing techniques for creating a good experience of your library, SDK or developer tools.

UX design is finally getting the attention it needed. That’s a fact. I worked with multiple designers. I teach in a school for designers. Hey, my wife is a UX designer! And they all are crazy focused on the users, the look, the feel, click, touch, attention and so on. How great is that!

Now imagine my humble self trying to build something that is supposed to be used by a developer. A set of tools that make building apps easier for her*. You know, nothing to understand there if you’re not a programmer. Did I mention it was at work, not a pet project? So it had to go through a design review.

Long story short, I got loads and loads of feedback on the features and the end-user experience of the only UI widget in the package containing ~30 methods and quite a few abstractions on top of a public API.

That’s how I ended up using whatever I knew from my designer friends and family to become a (makeshift) DX designer.

Here’s what I learned.

 Experiencing the experience

Wear your developer’s shoes.

This is even more important than it is obvious. User Experience seems to me like the science of common sense, so why would it be any different in this case?

tip. Write code that uses your tools straight away. Build a whole use-case, not a unit test.

And when you write it, try to make it as short and as simple as possible. You’ll instantly see how uncomfortable your new function is. Or that a response is missing some important data. Building a whole working use-case is the best you can do.

All that code will be a great set of examples for your tool’s documentation too.

tip. Write example user code before creating a function or a feature and it might design itself.

Your laziness is your best advisor.

tip. Forget copy-paste. Write each example like it was the first.

Some things might turn out annoying…

Luckily, copying from documentation is allowed. You do create documentation as you go, right?

tip. Imagine requirements the developer has to fulfill.

 Make all the decisions and then change them

tip. Every option needs a reasonable default. No excuses.

Remember to try running you tool without any options too. It doesn’t have to make sense when you do so, but it should work.

tip. Everything is an option. The developer should be able to configure every decision made in code.

 Need inspiration? Look for help instead. Desperately.

I guess everyone will look for inspiration in other libraries, SDKs and tools. But there is another source of answers to the “how” questions.

tip. Ask your search engine how something is done and assume the developer will find it too.

When designing the usage pattern of a function or an API, or any flow for that matter, try checking what your dev would find if she looked on the Internet. Search too.

Search “how do I upload a file from javascript” when making an uploader function and see how it’s done in the wild. Your function should be used in a similar way, but with less code. If anything is lengthy or hard to read in the examples you find, that’s the part you need to hide from the developer.

 Wander off the happy path

An error occurring is bad enough, why make it worse with bad error reporting or handling?

tip. Never put off handling errors. Build examples that fail and make them do so gracefully.

Introduce errors to your tool’s code and see if they are properly reported too. If your code doesn’t throw errors, it doesn’t mean it never will.

tip. Hide errors from the developer when she shouldn’t care. (apply carefuly)

I built a facade for a public API which has a query-per-second limit. The developer will never get the limit reached error, because whenever this error is returned, my code waits the remaining part of the second and queries again. It’s totally transparent for the developer because otherwise it would just be annoying.

 Keep your interface clean

Only expose methods and/or resources that are a part of your interface. The developer will try to use anything you let her. And whatever she uses, you can’t change in the next minor version, because you care about backward compatibility. You do.

tip. Make sure there is no access to methods and fields that should be private.

In JavaScipt use revealing module pattern instead of object constructors. Avoid new and this unless you explicitly want the developer to leverage inheritance.

 Don’t miss her first steps

That’s not an advice for young dads. The hardest thing for your developer is to get started. You need to make it as easy as possible.

tip. Create a boilerplate or an example that the developer can just copy-paste and run.

If your tool needs an external service to work, create a mock for at least one example so it can work out of the box.

tip. Check if the first steps are still easy every once in a while.

It’s easy to forget what your API authorization looks like when your test server’s session is valid for two weeks. The initial steps are easy to overlook, because you only do them once when testing.

nodejs tip. Clone your code to a new location and run npm install from time to time to check if your dependencies still resolve correctly

 Consistency, consistency; consistency.

There’s nothing more confusing than two similar functions with different input format.

tip. Good code reuse gives you consistency for free.

If you have a single function for making queries across all your codebase, there’s no way it could get inconsistent.

 Buy a nice wrapping paper

Pay attention to finishing touches. Filenames should be descriptive, folder structures need to make sense, documentation needs to have an entry point. Remember to include a license. Inform about the file sizes or memory footprint.

tip. If you’re building a library or an SDK make sure it installs easily. Everyone hates copying your folder with images to a location you hardcoded.

I’ll be writing more about organizing and packaging JavaScript tools with browserify, so stay tuned.

* I always enjoyed the user being referenced to as “she” in the depths of the most complicated linux howtos obviously targeted at nerds. A lovely and welcoming case of wishful thinking, that is (slowly) coming true.


Now read this

Everything is an array index

Javascript engines never cease to amuse me. Let’s look at our good old Array.prototype.splice [1,2,3].splice(0,1) //returns [1] [1,2,3].splice(1,1) //returns [2] [1,2,3].splice(undefined,1) // 1 [1,2,3].splice(false,1) // 1... Continue →