Review

This isn’t a coherent book, it’s a collection of short articles on DX.

You Might Also Like:

Practical Recommender Systems

Recommendations have become an important part of most products. As such, Product Managers need a good understanding of the underlying technology. Although the theory can be complex, having an understanding of the tradeoffs and limitations of your system is crucial.

andrewclark.co.uk

Book Review and Summary: Designing Machine Learning Systems by Huyen Chip for Product Managers

Get a comprehensive review and summary of the best-selling book "Designing Machine Learning Systems" by Huyen Chip, specifically tailored for product managers. Learn how to apply the key insights and takeaways from this must-read for tech leaders and professionals to your role as a product manager.

andrewclark.co.uk

Developer Experience

A short and accessible introduction to DX. The author does a good job of comparing and contrasting to UX. I hoped this book went deeper into the practical realities of doing discovery work in developer facing domains.

andrewclark.co.uk

Key Takeaways

The 20% that gave me 80% of the value.

Developer Experience (DevX) mirrors user experience principles but focuses specifically on developers' interactions with software tools. Good DevX encompasses the usability of tools across documentation, command lines, SDKs, libraries, APIs, and other touchpoints. Successful DevX requires well-documented services with comprehensive getting started guides and practical sample code for common use cases.

The API onboarding process frequently fails developers at critical transition points. Organisations should analyse their funnel to identify experience-related dropouts and help developers cross the "API chasm" with robust code samples, interactive sandboxes, and freemium models allowing testing within 180 seconds. Peer support enables instant answers, complementing traditional documentation which must balance digestibility with completeness. Time to First Call (TTFC) is a vital metric measuring how quickly developers can make their first successful API call after signup—ideally within minutes, not hours.

Effective API documentation requires understanding different audience needs (buyers versus users). It must include essential components: authentication methods, comprehensive resource descriptions, error messages with troubleshooting guidance, terms of use, and change logs. Documentation best practices include avoiding jargon, documenting all requests and responses, providing additional resources, offering getting started guides, and including sample code—elements that transform a usable API into an exceptional one.

Poor developer experiences commonly feature lack of OpenAPI specifications, non-standardised documentation formats, insufficient real-world examples, manual integration processes, inconsistent behaviour, questionable deployment options, and unnecessarily restricted access to documentation. API sandboxes should isolate testing environments, provide free access, accurately recreate production behaviour, properly implement authorisation, and account for gateways or proxies.

Developer marketing for APIs requires an education-first approach rather than promotional content. Organisations must understand the actual buyers (who may not be developers), recognise true alternatives and competition, and focus content on solving developers' real business and technical problems. Many organisations benefit from dedicated Developer Experience teams with responsibilities spanning API design guidance, quality assurance through consistency, developer tooling (including SDKs and reference implementations), and comprehensive developer relations.

Outstanding developer experiences prioritise quick onboarding processes, robust self-service tools, informative developer account dashboards showing usage metrics and billing information, and active developer communities. Developer advocates can create and maintain personal relationships with key users. Organisations should balance time between awareness, education, and customer retention activities, measuring success through KPIs like weekly active tokens and time to first "Hello World."

For API products to succeed, they require consistency across nine critical areas: naming conventions and endpoint structures, design paradigms (whether REST, SOAP, or others), error handling with standard HTTP status codes, documentation quality with efficient navigation, support channels and feedback mechanisms, versioning practices with clear communication about changes, security implementations meeting consistent standards, authentication procedures including credential management, and platform specifications that directly drive documentation.

Deep Summary

Longer form notes, typically condensed, reworded and de-duplicated.

Preface - What is Developer Experience?

• Developer Experience (or DevX, DX) - is like UX, but about the experience developers have while using software tools.
• DX - is about usability of Developer Tools across all of interaction points on the developer journey (documentation, command line, SDKs, libraries, API endpoints or sandboxes).
• Services with good DX are typically well-documented and have a good getting started guide and sample code for common executions.
• Developer Facing Tools:
• SDKs (Software Developer Kits) and code libraries
• APIs
• Open-source code repositories
• Code libraries, sample code, or tutorials
• SAAS (Software as a service)
• PAAS (Platform as a service)
• IAAS (Infrastructure as a service) and CloudOPs
• Specifications and open standards
• Consider the entire developer journey:
• Discovery: How easy are you to find?
• Onboarding: How easy is it to start? (documentation, reference material, code tutorials)
• Time To First Call
• Time to First Hello
• Time to Value - Business Value
• Testing and Production: Behave as expected? Reliability. Maintainability. NFRs.

API Onboarding is Broken (and how to fix it)

• Analyse your funnel - are dropouts due to a poor developer experience.
• Help developers cross the API chasm with code samples, sandboxes and freemium models so they can try the APIs quickly before committing.
• API Chasm: Discovery → Understand (3 seconds) → Test API (30 seconds) → Test in own code (3 minutes) → Heavy Use
• Developers should be able to test APIs within 180 seconds. Article
• Peer support (faster than 24/7 support) enables instant answers.
• Documentation tradeoff: digestibility and completeness.
• Solution: help should dispense automatically by design when needed
• Can you embed community knowledge and examples into documentation?
• Analytics: Track, measure and iterate on your developer portal / documentation / experience.
• A good starting point to documentation is using a OpenAPI spec and Swagger tools.
• Time to First Call is an API metric - helps you think about removing roadblocks in the process of signing up and getting started with the product
• Ways to help:
• Code samples
• Extensive documentation
• Communities (as well as traditional support)
• Iterating based on feedback and analysis

Personal Take: Tesla Autopilot, each steering wheel interaction is a sign we need to change. We should treat each support call or community post like that too. As a signal.

5 Ways to make your API more self-service

1. Decrease Time to First Call (TTFC)
2. Provide a sandbox for testing
3. Instant account / API Key Issuance
4. Exposure to audiences (market places, partners etc)
5. Documentation that’s easy to understand, comprehensive and easy to navigate

Best practice for Creating Useful API Documentation

• Understand the audience - buyers vs users
• Essential components of API documentation:
• Authentication: how to access your API
• Resources: what your API can do (every endpoint, standard commands and responses).
• How to name endpoints (link)
• Error messages: Each one and how to fix common issues
• Terms of use: limits, constraints, branding, usage etc
• Change log
• Best practice for API Documentation:
• Avoid jargon
• Document all requests and responses
• Include additional resources (don’t want users to leave you and go to a search engine)
• Include a getting started guide
• Include sample code
• Make the difference from being usable to being frustraiting.

7 Best Practices for API Sandboxes

1. Isolate your sandbox
2. Provide free access
3. Recreate production behaviour
4. Remember authorisation and authentication
5. Account for gateways or proxies (rate limiting)
6. Review sandbox usage - look for unexpected usage
7. Consider chaos mock - code under variability and edge cases

What does a bad developer experience look like?

1. Lack of OpenAPI specifications
2. Documentation in non-standardised formats (needs to be searchable, understandable and easily integrated into any format they desire)
3. Lack of examples (must give real-world examples of the API in action)
4. Manual integration (OpenAPI tools allow automation)
5. Lack of consistency (your API needs to be predictable and stable)
6. Questionable deployment options (make sure you have the right deployment options)
7. Restricted access for documentation (let prospects see your API documentation)

Why Time to First Call is a Vital API Metric

• The signup process → making an initial API call = Time To First Call (TTFC).
• Any GET request?
• TTFC = developer accessing documentation or signing up for an API key and making their first successful API call (of any complexity)
• You want TTFC to be minutes not hours.
• Exploring ‘First Call Motivators’: Enthusiasm, willingness to forgive flaws etc depends on motivations:
• Searching for a solution to a particular problem
• Heard about your service and are curious
• Project or role requires they use your service
• Improving Your Time to First Call
• Extensive documentation
• Demonstrate use cases and examplees
• Assessing Roadblocks (API keys etc)
• Encourage making calls early
• External tools: POSTMAN Public Workspaces

Developer Marketing for API Companies

• Education not promotion approach to reach a developer audience.
• Know your buyers, target companies etc (those involved in the purchasing decision, support and run folks too). Not necessarily the developer.
• Know the real alternatives and the real competition. How do you compete with current tools?
• Developer content mind trick → help developers solve the problems they have. Focus on the business and technical problems your product solves.

Why Your API Needs a Dedicated Developer Experience Team

• Dedicated developer experience team that empowers your users, by making it easier to understand, build and integrate
• Developer Experience: understanding developers, their needs, abilities, values, what they’re trying to accomplish, what tools and techniques they’re currently using, the integration points and how they feel while using the product.
• Developer Relations - a vital component of a comprehensive
• Evangelists, advocates, writers
• DX is to APIS as UX is to UIs. A great DX can be the key differentiator.
• DX is the acquisition of knowledge needed to implement anAPI. Make it easier, more digestible and implementing it simple, make the lives of developer better.
• Your developers might appreciate a DevX team to help them craft a better experience.
• DX can increase market share.
• Diverse multi-disciplinary team with 4 main responsibilities
1. API Design (Design guidance, review, style guides, specifications)
2. Quality assurance (quality through consistency) (contract testing, specification testing, style guide testing, docs and tooling testing)
3. Developer tooling (let them use it)(code samples, demos / reference implementations / SDKs and libraries, specifications, definitions and schemas)
4. Developer relations (documentation / tutorials / FAQs, release notes, system status info, media content, training and materials, user research studies, events and community)

Tips on Creating Outstanding Developer Experiences

• API products that streamline DX tend to increase interest and retain a following.
• Developer portals can help with discoverability, quicker onboarding, and accurate documentation.
• API design is important too - best practice.
• Hallmark for DX is meeting your users’ needs → and getting them to hello world as quickly as possible.
• Be good at every stage but particularly onboarding - create an awesome flow that helps you start pinging the API quickly.
• Self-service tools are incredibly appreciated.
• Developer Account Dashboards (metric usage, billing information, release notes, upgrade guides) - all the things you need ot maintain your account (reset API keys, consumption rates, etc)
• Developer advocates: create and maintain personal relationships with your developers.
• DX communities: unique makeup, community discussion forums. Nurture and empower them. Focus on the most value-generating activities.
• DX Time and Task Management - Value vs time and resources.
• Balance awareness, education and retaining customers through improving their DX
• KPIs to improve DX - 2 north star mertics:
• Weekly Active Tokens (e.g. product usage)
• Time to first HelloWorld (or more meaningful metric)
• Search for insight in the following areas:
• Content: views of developer-centric content, including tutorials or videos
• Forums: look for trends in engagement on support questions
• Talks: consider feedback from events and lectures
• Hackathons: monitor the usability and hiccups during developer and onboarding at live events
• Building Outstanding DX: Final Thoughts:
• Create a quick and easy onboarding process
• Build killer self-service tools and documentation
• Prioritise developer experience investments carefully
• Using the right data and feedback to improve

How to find an audience for your API?

• What does your API do in a single sentence
• Carry targeted messaging throughout documentation and code samples
• Take an educational not salesy approach (use market places)
• Make sure you understand:
• What brought them to your API in the first place?
• Did it solve their problems in a way they hoped?
• What about the API in its current state works well?
• Is there anything that could be improved?

Pointers for Building Developer-Friendly API Products

1. Know your developers
2. Be obsessive about naming
3. Always stick to your process: Discovery → Design → Development → Launch
• Must be needed today but also 5-6 years in the future
4. Build a complete ecosystem
5. Think API governance - how you organise and govern the API suite. APIs should feel consistent.

9 Areas of Consistency for Great Developer Experience

1. Naming and endpoint consistency (clarity, casing, grouping, accuracy)
2. API design paradigm (if REST follow RESTful core tenants, if SOAP follow SOAP)
3. Error Handling (HTTP status codes)
4. Documentation quality (accurate, navigation, efficient, brevity
5. Support and Feedback (Support, communication, training, feedback)
6. Change and Versioning (consistent, communicated well, methodology to sunsetting and deprecating)
7. Security (consistent endpoints, with consistent security standards, baseline monitoring and response methods)
8. Authentication and Authorisation (API keys, handle credentials on account expiration)
9. Platform Consistency (specification should drive the documentation directly)