Usability is about understanding what someone else needs and giving it to them, not how to get them to do what you want.

  • People rarely read anything.
  • People are looking for something useful.
  • For developers code samples, docs, and the API itself are useful.
  • Everything else is an obstacle.
  • Treating people as “users” before they use your API may reveal a fatal bias.
  • You don’t get to decide what is considered marketing vs what is useful information. The consumer of your site/app does.
  • Usability testing taught us the above.
  • Anything that stands between a person visiting your site and directly trying your product is an obstacle to both the person and you.
  • Let the person visiting decide how engaged they want to be.

TLDR; The long version.

When Orchestrate‘s NoSQL database service for developers went into general availability earlier this year, we were optimistic we would have a successful launch. After all, our beta testing had revealed a lot of interest among developers for our product – despite a website one could charitably call “bare bones” and a stripped down UX for the actual service. So when launch came, we figured a new website that told our story – the story of why we felt it important to build a database service as unique as ours – would vastly increase engagement and drive up our conversions. We thought we had made a great case for who we were, what we were doing, and why.

By every indicator – traffic, conversions, paying customers – our launch was a success. For a few weeks we saw the number of visits and signups climbing rapidly and in lock step. However, beneath these numbers we were seeing another trend: half or more of our sign ups were not coming back after checking us out. And while we were getting much higher numbers, our conversion rates had dipped. We were prepared for the post-surge slump many startups face after a big launch but what we hadn’t expected to see was a decrease in conversion rates.

What could make people who had gone to the trouble of signing up take one look and shrug? We did surveys to try and unveil the root of the problem. People told us they loved our website, they thought our API was simple and straightforward, and they asked for even more emails reminding them to use the service. Many promised they really were interested and would come back some day.

We weren’t satisfied with the answers, so we contacted a local usability expert who helped us design a study involving developers that reflected our best understanding of our most frequent visitors at the time. We ran them through the website and product, and what we found opened our eyes to just how far off the mark we, and many others with “beautiful” Websites, turned out to be.

The Truth is Like A Punch to the Gut

It didn’t take long for us to identify the cause of our decreased conversion rates. Mere hours into the study, which felt like a cross between Mission Control for the Apollo 13 mission and a jury room after three weeks of deliberation, we were forced to face some facts. “But our site is beautiful,” we muttered as we stumbled aimlessly around the remote testing room. “You all told us so. We have the survey results right here.” But the truth was, our target user wasn’t interested in what we had to tell them. At all. TL;DR. This is what we learned:

Make code (or whatever the product is) the content. Developers skip text in favor of code – they consider it marketing. When faced with text that explained the code and product, developers always – without fail – choose code samples and ignore copy. Most customers – even non-developers – rarely want to be told why they should use a product and prefer to vet it for themselves. Context that converts a developer to a user can only come from combining documentation with actual examples of functionality.

Get real about who a user really is. No one is a “user” until they use an API or product repeatedly. Until then, they are what they are: curious visitors. Words like “user” only bias you towards the unknown person visiting your site.

Give them the product as soon as you can. Stop trying to convince them to use the thing you provide or sell or whatever – just show them the product and throw them into the sandbox. We made a mistake by not allowing access to our product’s functionality up front. People signed up because they had to to actually experience the product to see for themselves, not because they wanted to. Better informed and knowing what to expect, low-quality leads will remove themselves from the pipeline and the right users will bubble to the surface, fast.


Follow the Pareto principle. You’ve heard of the 80/20 rule – that a small selection of your user base will drive the majority of your revenue. So, profile actual users to find your sweet spot. “Personas” are plastic, produced, and likely not on target. It is difficult to capture the magnificent uniqueness of real users and their use cases – they are odd, contradictory, ambitious, friendly, generous, vain, and amazing. They are the 20%. Pay close attention to them.

Simplify. Simplify. Simplify. Based on the usability testing, we decided to clear away text from the initial web experience, and move copy meant for product managers and executives under the Product tab. We cut out pages and non-product images. Instead of telling visitors something that feels important to you, or explaining what something does rather than show them, let them try your product firsthand. Remove anything that lengthens the path for a visitor between typing in your URL and deciding whether use the product.

A final thought for those who chose to read this far: We are quickly becoming a nation of article-skimming bloviators with a half-formed opinion on everything, and it is not our fault.

As I began this post, I came across an article by Karl Taro Greenfeld in the New York Times, Faking Cultural Literacy, which concludes we are essentially a culture of grandstanding skimmers who, having read a headline or a few bullet points in summary, feel no hesitation to offer strong opinions on the topics about which they have read only a little. It made me immediately think of a blog post we recently published that garnered over 7000 unique readers, dozens of Reddit comments full of refutations, accusations, and plaudits, and had an average visit time of 45 seconds. And hardly a single signup. This pattern repeated itself with other posts – lots of visits, lots of comments, a little controversy, and few actual readers.

Had I read the Times article two months ago, I would have agreed with its author and dismissed developers as, like the rest of us, a bunch of cynical headline readers with one finger on the up or down vote and another on the tweet button. That was before we woke up to something startling – the only thing that stood between potential customers and adoption of our database API was us. Or more specifically, us trying to tell people why they really, really, REALLY needed to use Orchestrate.

We learned a valuable lesson: TL;DR is a sign of respect for the potential user. And if you want people to use your product or service, give it to them to use. Don’t tell them about how great it is and why they will love using it. Maybe skimming is a defense against all the crap we throw at users, when we should really just show them the goods and get out of the way.