This is the blog of Adam Kalsey. Unusual depth and complexity. Rich, full body with a hint of nutty earthiness.
Developer Experience Principle 6: Easy to Maintain
Freshness Warning
This blog post is over 3 years old. It's possible that the information you read below isn't current and the links no longer work.
17 Oct 2020
To have a successful developer experience, developer products must be Easy to Maintain. Developer products have lots of things in the periphery. Documentation, SDKs, sample applications, and management tools. If you can’t easily maintain these, they’ll drift away from the APIs. The reality a developer is working with will be different from the reality you’re trying to create.
Establish the habit of giving the tools your provide your developers the same attention that you give the product itself. Cleaning a kitchen is easier if you don’t let it get overly messy. Maintaining your developer tools is easier if you keep them up to date as you update the product. Focus on ease of change of product internals within your team. Your developer tools are not the place to accumulate technical debt. If it’s hard to get a new error message to show up in the debugger you offer on your site, you’ll ship the error before you change the debugger. This will confuse developers.
If your documentation is hard to update and has the same information scattered everywhere, they’ll quickly fall out of date. Nothing frustrates a developer more than spending a bunch of time debugging their application only to find that the code they wrote was wrong because the docs were wrong. You can make it easier to maintain the documentation by minimizing the number of places you put a piece of information. Your shipping management API docs might list each country you can send a package to. This list might show up in lots of places in your documentation: the API reference for creating a shipment, a tutorial showing how to create a shipment, or the README of a sample application for example.
Instead of providing the full list in each of these places, you might have a second page that lists all possible destinations. Or only list the destinations in your API reference and point to the reference from the other types of documentation.
Look for opportunities to automate your documentation. You might be able to update your API reference from the API metadata that your developers are already producing. At Tropo, we offered an API to buy phone numbers, and that API could list all the different countries where numbers were sold. The documentation used that API to get a list of countries so that several times a day the documentation was automatically updated with the current list of offered countries. That way, as soon as the product supported a new country, the docs showed it.
When making your product Easy to Build with you created SDKs and code libraries to let developers use your APIs in their preferred programming language. Making these easy to maintain means reducing the number of SDKs you offer. Cutting the number of places in each one you’ll need to change to support new API updates. If you offer five SDKs and every SDK you offer needs a new change made in four places you’ll have to make twenty changes every time the API changes. Add a sixth SDK? That’s twenty-four changes. That’s 24 opportunities to introduce a bug into your SDK - and your developer’s applications - for each API change.
Some companies solve this by using code generation tools to maintain their SDKs. Some limit their SDKs to only the couple of most popular options. Most try and control how many updates a particular SDK needs to support an API change. Your API design, staffing, and sophistication will all influence exactly how you make your SDKs Easy to Maintain.
Some of your customer developers will create and publish their own SDKs. Encourage this behavior by promoting these community-produced SDKs alongside the official company-maintained ones. Have your support staff learn the most popular ones so they can offer support to those using them. Nurture the relationship with the creators of these SDKs. Give them early access to new features so they can ship their SDK at the same time as the new feature.
Crowdsourcing can help make your product Easy to Maintain. Open source your SDKs and create a clear policy around how you accept patches or pull requests from outside developers. Credit people that contribute to the official SDKs. Open up your documentation to the developer community to let them propose changes. Create a workflow that allows you to quickly incorporate changes where appropriate.
Keeping your product Easy to Maintain will improve the lives of your team and your customers. It will help keep your docs up to date. Your SDKs and APIs will be released in sync. Your tooling and overall experience will shine.