What is DX and why does it matter?
Developer Experience is the new User Experience
What is Developer Experience (DX)?
Put in programming terms,
Experience_type = “DX” if user.role == “Developer” else “UX”Or in plain English, your primary focus should be Developer Experience if the majority of your users are developers.
It’s not a difficult concept to grasp, so I won’t belabor it any further. However, while it’s easy to understand what DX means, it can often be very difficult to deliver exceptional Developer Experience, and it can be difficult to find non-developer-first companies that are actively focused on it.
What makes for good DX?
This is a pretty broad question, so I’ll break it down into a few general categories with examples. For my examples I’m going to assume the product is a RESTful API serving JSON, but most of the same general rules apply whether you’re building an API, a library, or a command line tool.
1. Respect Applicable Standards, Architectural Styles, and Protocols
This should be pretty self explanatory, but if you’re building a REST API, you should at least adhere to the basic RESTful design principals. The same goes for HTTP error codes; they’ve already been defined are are well know and understood by developers, so avoid things like mapping concrete errors to different error codes. These are just a few examples, but the same principal applies regardless of product or protocol you’re serving.
Of course, there may be exceptions where you need to bend this rule. Do so sparingly and only after re-examining that your exception either greatly reduces complexity or lessens potential confusion to your end user.
2. Be Consistent
While you should definitely be consistent with Standards, Styles, and Protocols, it’s also of paramount importance that you stay consistent with yourself. This applies to many different products as well as factors within a product. If your product is a library or SDK, make sure you’re consistent with you method naming, code style, and feature usage. If your product is an API, make sure you’re consistent with resource naming, verb usage, payload requests/responses, headers, field naming, etc.
3. Documentation Counts (At all levels)
I can’t overemphasize this one enough; Documentation is incredibly important. This includes obvious things like API documentation (preferably a standard spec like OpenAPIv3), READMEs, and product documentation, but also extends to tutorials, code examples, and method documentation/code comments.
While for internal code you may follow the mindset of writing self-documenting code and leaving sufficient comments, when it comes to externally published code there’s no shame in over-documentation. Don’t fear making liberal use of code comments and make sure that you add documentation for every public method and all associated arguments and behaviors. This also extends to release notes and changelogs.
Ex: A great README from Postman
If you have the good fortune of having a tech writer embedded in your team or company don’t take them for granted — work with them to give them the information they need. Like quality, documentation should be the responsibility of the entire team, not just the tech writer.
4. Be Transparent
Transparency is especially important for developer facing products. As developers, you’re not doing yourself any favors by trying to pull the wool over their eyes — they know a bug or security issue when they see one. This accounts doubly so for open-source projects where developers can see the changes you’re making. So always acknowledge bugs and issues in your changelog and give background and reasoning as necessary.
If you’re product is open-source it’s also a good idea to leverage an open CI solution is possible. This lets users see how the product is tested and follow the CI process themselves if they make any changes.
Finally it’s also nice to share code quality metrics with your users. Things like build status, download counts, and code coverage (I know this is an opaque metric).
What makes DX Difficult?
While I find good DX to be more common at companies that are primarily developer focused, especially those where their product is code (twilio, stripe). DX seems to have issues is when the developer is not necessarily the primary customer, but merely a single facet of the business, or simply an alternative way to consume the product. For example, Apple was called out recently for the state of their developer documentation. As someone who has tinkered with iOS and macOS development in the past, I have to agree with the author.
So what makes good DX so hard?
Developers are focused on other things
Arguably, since developers are more involved in developer focused products, with less input from UX/Design and traditional product documentation writers, they are in the best position to improve DX. Unfortunately, developers often have their minds on other technical matters and less on improving documentation or making other changes if the code is “technically” already functioning as expected.
While some developers follow a similar approach to “It’s not done unless there are automated tests”, this mindset is not universal and many developers seek to wrap up their work with the least amount of effort spent on documentation as possible.
DX isn’t sexy (to most)
This point is similar to the last, but the things that make DX great often aren’t flashy or exciting. While you can definitely improve your DX by spending time improving documentation, writing tutorials, or adding examples of more complex workflows, these activities are usually not as exciting as adding a new feature or even handling other tech debt.
It takes conscious planning, governance, and diligence
Good DX also requires more than just time spent on documentation. Creating a cohesive product that will delight developers requires a great deal of planning, governance, and testing, especially on large products that have more than a single contributing team. Keeping consistency among a large number of endpoints controlled by different teams will required shared standards between teams and likely a responsible party to provide some level of governance and review.
Automation can help
Tools like linters and formatters can help to avoid code consistency problems. For example, black for python is an opinionated code formatter that requires you to adopt their specific formatting, but in return reduces time spent crafting your perfect code formatting rules or arguing the between minute details. Tools like this are even more powerful if you can automate their usage by adding them as build steps or as a pre-commit hook.
In addition to linters/formatters, tools such as documentation generators and quality measures like extensible contract tests can help you automate your way to better DX.
