Skip to main content

Ben Ahmady & Minh Nguyen - Developer Experience as a Product

API the Docs Virtual Event Series 2020 Recap

This talk was presented at API The Docs Virtual 2020 event series on 18 November. We are honored to share the video recording, slide deck, and talk summary below. Enjoy!

Visit the API The Docs 2020 recaps overview to explore all presentations this year.

Ben Ahmady and Minh Nguyen

Senior Technical Writer and Group Product Manager at Onfido

Ben and Minh's presentation (video recording)


Ben and Minh's slides

Include product thinking and product management practices into API building process. How can that yield in a really delightful Developer eXperience?

Focus on the problems. That helps you think about designing and delivering great APIs.

Beyond the code

Approaching from product management perspective

Thinking about DX and APIs as fully machine-readable code has multiple consequences that can lead to potential mistakes:

  • DX would be understood as an engineering thing, so the engineering team would have to deal with it.
  • Going into implementation and design and forgetting the reason why people care about your product.


  1. Customers don’t use your API because they like you, they do it because it helps them solve a problem.
    • Customers care about use cases not the product itself.
      • For example:
        Product: Payment API
        Use case: collect money easily and securely
    • Good APIs:
      • Flexible: solve multiple problems
      • Opinionated: optimized to solve the problem that most of your customers use them for
    • There are many use cases of the same data:
      Going into proper research, going beyond code, might help you discover that people use your API/data to solve very specific problems.
  2. APIs have to be designed to solve a customer problem, but in a way that supports the business objectives.
    • Define tracking metrics:
      • Health metrics: how performant and reliable are your systems
      • Growth metrics: how good you are at acquiring, activating, and retaining customers
      • Feature metrics: how effective you are at solving customer problems
    • Going from technical level through business outcomes (like quick go-live, retained and renewing clients) to happy clients.
  3. Methodical prioritization: pick your battles, pick the things to invest in
    Choose a framework toolbox, as long as it is:
    • Evidence-based
    • A shared exercise
    • Around common objectives

Product discovery

Invest in discovery before you jump into building

Make sure as much as possible that you are on the right track before you delve into delivery.


Make sure you know:

  • Who interacts with your API?
  • Who benefits from the value of your API?
  • What motivates them?
  • What environment are they in when they use your product?
  • What state of mind are they likely to be?

Make sure to:

  • Avoid tunnel vision > consider the holistic developer experience
  • Avoid individual heroes > take people on a collective journey
  • Avoid local optimization > be smart when picking which level to pull

Validate for utility and usability, not only feasibility.

Execution excellence

Going from:

  • Developer-lead outfit:
    • Documentation was well maintained, almost exclusively by developers and by those in engineering


  • cross-functional team:
    • Documentation as a visible part of the product
    • Distribution is key
    • Everyone is technical in a sense - many skills off the shelves can be integrated into DX

Key stages:

  1. Rebranded client interfaces:
    • We expect our customers to generate API tokens to authenticate against a live production and sandbox APIs
    • Make this the as good an experience as you possibly can and think about that how it fits in the overall DX
  2. Token cycling and management
  3. New quickstart guides:
    • Simpler API Ref = simpler documentation = :)
    • Ready-to-copy documentation
    • Migration guides
  4. API v3:
    • Much simpler that can be caught even in the visual impact
    • Look in where users were tripping up, where invalid requests were coming from
    • Try to understand from the customer’s perspective, what could be improved
  5. Improved analytics
  6. Developer hub revamp:
    • Having a little bit of fragmented documentation isn’t necessarily a bad thing, as long as you think carefully about how these things navigate within your overall experience.
    • Docs hosted on Github
  7. Custom client libraries
  8. Separating product and tech content:
    • Product docs: what the product actually does, help you to think about different personas naturally and intuitively
    • Technical docs: how you can actually use it
  9. New docs systemSee a Gatsby-based, custom, in-house development API Reference example on the slides

Holistic API eXperience

Isn’t just about the customer’s experience, but how we can help you as an organization

Segment the different elements:

  • Reference documentation
  • Information architecture and tooling (all the documentation surrounding the peripheral tools which facilitate DX)
  • Process and feedback


  1. Make changes based on the best assumptions or user research
  2. Deploy changes internally with CI/CD (Git Lab)
  3. Send URL via Slack, email if Git diff not possible (not every contributor is a technical person)
  4. Receive feedback on several places
  5. Make more changes
  6. Repeat 4-5


  • Treat the user experience holistically
  • Distribution is key
  • We are all “technical”
  • Assumptions aren’t always bad
  • Feedback is vital
  • Simpler overall experience makes everyone happier


Sign up to our Developer Portal Newsletter so that you never miss out on the latest API The Docs recaps and our devportal, API documentation and Developer Experience research publications.

Sign up


Articles on devportals, DX and API docs, event recaps, webinars, and more. Sign up to be up to date with the latest trends and best practices.