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.
- 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.
- 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.
- Methodical prioritization: pick your battles, pick the things to invest in
Choose a framework toolbox, as long as it is:
- A shared exercise
- Around common objectives
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.
- Developer-lead outfit:
- Documentation was well maintained, almost exclusively by developers and by those in engineering
- A 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
- 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
- Token cycling and management
- New quickstart guides:
- Simpler API Ref = simpler documentation = :)
- Ready-to-copy documentation
- Migration guides
- 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
- Improved analytics
- 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
- Custom client libraries
- 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
- New docs system: See 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
- Make changes based on the best assumptions or user research
- Deploy changes internally with CI/CD (Git Lab)
- Send URL via Slack, email if Git diff not possible (not every contributor is a technical person)
- Receive feedback on several places
- Make more changes
- 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