On Developer Experience

Here's what I believe creates a great Developer Experience (DX):

Frameworks and Libraries

• Make onboarding fast: You should be able to try a new tool in one command. For example, npx create-next-app or brew install bat. Then, should it quick to iterate and see the value of the tool, with fast feedback loops to the developer.
• Make upgrading easy: When making a major version change, limit the “blast radius” of the changes to make it easy for folks to update dependencies. Ideally, changes should start out opt-in with many months of lead time before landing in a major version. Then, major versions should include codemods – scripts that run code transforms to help automatically migrate code and fix breaking changes.
• Helpful error messages: When applicable, include hyperlinks in error messages to provide more context on how to solve the error. Your tools should be providing you feedback as you type. The faster, the better (e.g. type checking, linting) before runtime or compilation errors. Don't make me think.
• Strong defaults and conventions: Have an opinion about “the right way” to build software. For example, don't make me think about setting up routing, just use the file-system-based routing with Next.js. Don't make me configure compilation and bundling, just set up good defaults for me with webpack/swc/vite/esbuild.
• Provide escape hatches: The counter to strong defaults is to make sure there are escape hatches when the developer wants to break from the standard configuration. One reason Next.js was successful in the beginning was being able to easily override webpack without leaving the framework, whereas CRA required something like craco after ejecting.
• Reduce risk with dependencies: When you npm i next, you only install 13 dependencies from npm. The rest of the dependencies are inlined into Next.js to have faster installation times and improved security. In the future, we'd like to turn Next.js into a single binary you can install.

Documentation

• Lead with code: Developers want to write code. Give them code examples as starting blocks. Don't bury the lede.
• Make it easy to find answers: Developers come to docs to learn the answer to a question, challenge, or problem they're trying to resolve. Give them the answer through multiple methods (video, text, tutorials, guides, etc.). Provide an AI-powered search which is indexed on the entirety of your docs content.
• Automated documentation: When documenting an API, it's helpful to generate the docs from the source of truth (code) to ensure they remain in sync. For example, Vercel's API docs are auto-generated from its OpenAPI spec.
• Not just the happy path: The documentation is a reference guide for developers trying to get work done. Often, this means searching for an error and looking for a solution they can copy/paste. It's important to document the workaround and hacks, too. I'd rather acknowledge a gap in the product and unblock the developer rather than leave them frustrated.
• Optimize for skimming: We all skim, especially when reading dense technical documentation. My eyes jump directly to code blocks, trying to find the solution to my given problem. Consider adding helpful code comments in the code snippets and showing multiple options or permutations of the desired feature/API.
• Be precise: Avoid technical jargon and idioms. If you're using an acronym, spell it out the first time and don't assume the reader knows what it is. Your docs should be accessible for both beginners and experts. Consider putting content that's helpful for experts but not critical for the happy path in collapsible deep dive sections.
• Progressively expose complexity: Keep the first-time experience simple while progressively disclosing more complex features as they continue building. It's not feasible to expect developers to learn about the entirety of the platform at the start.

APIs

• Don't break API workflows: API versioning should be intentional and explicit. Err on the side of over-communication when making changes to APIs and give developers plenty of time to update to new versions. I've personally enjoyed Stripe's API versioning – they have an excellent post if you want to learn more. I've seen some instances where AWS sends a deprecation email about an API that's been stable for years, plus gives them years of upgrade time.
• Let me try out APIs quickly: Some of my favorite API documentation allows you to generate an API key and try out endpoints in a few seconds. Some even recognize that you're already logged in and personalize the page based on your account information. Square does this well. I also like GraphiQL for this – you view the entire graph schema, make requests, run mutations, format your code, and more.