Developer Experience: What not to do
I remember the time I was interviewing for a product leadership role focused on developer experience. I decided to dogfood the product as a part of my interview prep, and set out to build a simple product using the company’s API. I grew increasingly confused and frustrated as I found myself jumping through hoops to get to the sandbox, then endured a nearly hour-long “how to” video before the UI to navigate the portal would activate. It was just one of a number of experiences I’ve had where the developer experience had the opposite of its intended effect.
“Knowing what to do is wisdom. Knowing what not to do is experience.”
— Unknown
In the spirit of sharing my experience, here are some guaranteed developer repellents:
Making them download a white paper. That person running for the hills? Your friendly developer. Ben Williams and Jakub Czakon summarized a developer’s goals perfectly in this post:
Devs, like other builders, want to:
know what the thing does,
see objective specs (docs),
test it out (free tiers, open-source, public sandboxes),
see how the product feels (code snippets, diagrams),
talk to their peers (community),
do it themselves (self-serve experiences),
know that it works with other tools they already use (integrations)
What they don’t want to do is to read a white paper waxing eloquent about the benefits of using a particular solution, and the theory behind the tech. Builders bias towards building, not towards theoretical explorations.
Have sales reach out within seconds/minutes/hours of sign up offering to discuss special volume pricing. Might as well try to catch a cat with a vaccum cleaner. It is a case of targeting the wrong person at the wrong time. Technical product purchase decisions involve two buyer personas at larger companies — the developers who will build with the product and their business counterparts responsible for the budget. Premature sales outreach to either persona before the developers have had a chance to evaluate a product is guaranteed to backfire. Purchase decisions for products to be used by developers at any successful company is never made in a vacuum without consulting the developers who will be building with them. Developers will not endorse a product until they have had an opportunity to evaluate the product to their satisfaction.
Block Proton Mail, Tuta Mail, and similar privacy focused email addresses from signing up. Just slap a “Keep out” sign on the front door instead. As Kyle Polar points out, fake accounts are a major issue when offering products with free trials. However, the solution is not to go into the database and bulk delete email addresses with Proton Mail, Tuta Mail and similar domains, and worse, block new sign ups. Developers in particular, are attracted to providers like Proton Mail and Tuta Mail because of their focus on privacy, security and encryption. Investing in developer marketing on the one hand while bulk deleting proton mail signups on the other is shooting yourself in the foot.
Bury devs in tech docs with a UI that’s like a game of whack-a-mole. Click one link, and BAM, another window pops up faster than you can say “developer overload!” If you’ve never been a developer but are focused on improving DevX, I highly recommend watching a developer at work before designing the documentation experience. Developers seamlessly switch between code and documentation, have streamlined workflows, and for most, cross-referencing docs spread across half a dozen tabs is a non-starter. Search is the most common way to access docs. Code samples that can be run in adjacent sandboxes, the ability to easily select and copy-paste code snippets, and the option to auto insert an account’s API keys into the sample code when logged into the portal go a long way in delivering developer delight.
Pre-announce future enhancements in the documentation. No empty stubs, no “coming soon,” no “will be supported next revision.” Less smoke, more fireworks. The docs should specify current behavior. Vague promises are confusing and give rise to questions for which the answers are unknown at the moment. Put yourself in the shoes of the developer advocate who is forced to say “We don’t know yet” when asked whether “coming soon” will support current implementation while trying to maintain some semblance of credibility as the product expert, and the reason why this is a bad idea will become evident. Developers want to know that the product will work reliably, now and in the future, and that the effort they are investing is worthwhile.
Put instructions before conditions in the documentation. It’s like following instructions to bake a cake only to find out you don’t have the powdered sugar the recipe calls for after mixing the wet ingredients, because the author decided to leave the ingredients list for the end. Few things are more frustrating than to work through multi-step instructions only to find out that they are not applicable to one’s dev. environment.
Put usage limits on the dev sandbox. It’s a sandbox. It’s meant for developers to kick the metaphorical tires of the product. Putting usage limits on it is akin to posting a sign: “Make sure your sandcastle doesn't exceed two inches!" after inviting everyone to a sandcastle building party.
Outdated repos with sample code incompatible with latest software versions is a bad look. Either a) keep the repos updated, or b) sunset them. Outdated repos with sample code that won’t build and throws errors is worse than not having any sample code at all. It makes devs question whether it’s a good idea to invest in building with a product that is not seeing an active investment of effort from the company that developed the product.
Lack of technical support and responsiveness to developer feedback. Few things are worse than feeling like one is stuck on a deserted island hearing crickets in response to a request for help when trying to actively evaluate a product. This does not bode well for a future where issues may be encountered in production. It’s a bright red flag that’s typically a deal breaker for developers.
Bonus:
Asking devs to “contact sales” to get pricing for a self-serve product. While this particular issue is not confined to developers, it’s particularly irksome to devs when the pricing is usage-based. Often, business counterparts will request devs to help estimate spending and optimize operational costs, and the level of enjoyment devs. derive from interfacing with sales teams to understand the intricacies of variable pricing is on par with pulling teeth.
My take: if variable pricing is critical to a company’s profitability, then the product is not suited for self-service. If building a self service experience, price transparency is a must.
What would you add to this list?
+ Only make documentation available after registration.