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.

• the developer is building a mobile app
• the app has to work in an iframe
• your widgets need to match the branding of the whole app
• the app is going to run offline

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 stackoverflow.com 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.