You have to master the fundamentals of building a developer-facing product before venturing into a more complex, way more expensive and more experimental territory.
"If you do a google search for the best developer portals out there, you are going to find a lot of impossibly high standards. [...]Through a lot of trial and errors, we've been able to come up with a list of the fundamentals [...] that we can double down on, to change the culture in our company for the product to be developer first."
Fundamentals that any company can do to improve their DX
In baseball, trainers teach the fundamentals to major-league players, too. Fundamentals are as important to a tiny startup that is just trying to roll out its first developer-facing product as for Stripe, Twilio, or Apple who have been doing this for a long time.
"Two things the developers really care about the most are Consistency and Reliability. Unless you have those, other stuff doesn't really matter."
Advocates for different needs
A lot of advocates are inside of every company. They are representing different needs and constraints and try to push certain things forward within your product. However, the most important goal is to ship a developer-first product.
- CFOs (chief financial officers) advocating for affordability: a premium developer experience might require additional expenses.
- CTOs (chief technology officers) advocating for simplicity: but a premium developer experience calls for support across various platforms and programming languages － it’s not so easy-to-build, nor easy-to-maintain.
- Relationship Managers advocating for the existing clients to be happy: maybe they will resist any changes to your product regardless it would make the DX better because they try to protect clients from any inconvenience.
- Security Architects advocating for safety: a developer-facing product should be transparent － allow developers in, who after a quickstart can start experimenting with how the product works before signing up for any real commitment.
- Developer Advocates: advocating for the agenda of your developers, can be a Technical Writer, a PM, or a Developer who’s involved in the product meetings and able to advocate for the Developers in those settings.
Be consistent and reliable, be oddly satisfying
- Your product should work, run smoothly, and be well-documented - these are what developers are looking for.
- Consistency means the product is uniform and predictable.
- Reliable means the product does what is expected to, every time.
- Developers avoid those products that look like it could work but it doesn’t.
Wrong approach: just because you built a product, your audience will come.
- Talk to developers at every stage of the product’s lifecycle.
- Document how you envision your API works before you start coding.
- Let developers help you build the product they want to use.
- Proactively ask for honest and critical feedback.
- Try to avoid superficial “yearbook answers”: We really like your API, the documentation is perfect and we love it! We were able to build a great product.
- If you’re looking for hard answers, you have to ask the hard questions: Which part of your implementation was more difficult than it needed to be? Which of the following improvements would have helped you the most during your implementation?
- Engage with the developer community.
- See how your product is used in real-time.
- Find out which questions don’t get asked.
- Can be a good recruitment channel.
Documentation － “the instruction manual”
- The simpler the better. Make it intuitive.
- Keep in mind the “15-Minute Rule”.
- It works if everything fits together, if it’s very reliable and consistent.
- Docs require a lot of iterations.
- Learn developers’ pain points and enhance the documentation to address these pain points.
Forums － it’s impossible to answer every questions in the documentation
- Stop answering questions in isolation, like Stack Overflow.
- Embed a form in your documentation or in your support page.
Support Channel －meet the developers where they are
- Remove communication barriers.
- Make it easy for your developers to get their questions answered.
- Start building a community, for example by establishing a Discord server with a dedicated support team.