Developer Experience Principle 6: Easy to Maintain

Freshness Warning
This blog post is over 2 years old. It's possible that the information you read below isn't current and the links no longer work.

Easy To Maintain 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.

More about the Six Principles of Developer Experience

Recently Written

The Trap of The Sales-Led Product (Dec 10)
It’s not a winning way to build a product company.
The Hidden Cost of Custom Customer Features (Dec 7)
One-off features will cost you more than you think and make your customers unhappy.
Domain expertise in Product Management (Nov 16)
When you're hiring software product managers, hire for product management skills. Looking for domain experts will reduce the pool of people you can hire and might just be worse for your product.
Strategy Means Saying No (Oct 27)
An oft-overlooked aspect of strategy is to define what you are not doing. There are lots of adjacent problems you can attack. Strategy means defining which ones you will ignore.
Understanding vision, strategy, and execution (Oct 24)
Vision is what you're trying to do. Strategy is broad strokes on how you'll get there. Execution is the tasks you complete to complete the strategy.
How to advance your Product Market Fit KPI (Oct 21)
Finding the gaps in your product that will unlock the next round of growth.
Developer Relations as Developer Success (Oct 19)
Outreach, marketing, and developer evangelism are a part of Developer Relations. But the companies that are most successful with developers spend most of their time on something else.
Developer Experience Principle 6: Easy to Maintain (Oct 17)
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.


What I'm Reading


Adam Kalsey

+1 916 600 2497


Public Key

© 1999-2023 Adam Kalsey.