Things break because an assumption made by the integrator is no longer correct.
The ability to predict others' assumptions allows you to react accordingly
If it hasn’t broken for a long time, we think it never will
"Breaking" is binary to assign blame
Some assumptions are so hard to not make, it is just inevitable and necessary
We should really think about potentially breaking changes
A few different examples of things that have broken other people’s stuff
Adding a mandatory field to an endpoint
Introducing a rate limit
Changing an error response string
Breaking apart database transactions
Changing the timing of the batch process
Reducing the latency on an API call
The right thing to do may still have the potential to break somebody else’s work.
”We need to help our integrators stop making bad assumptions.”
How do assumptions develop?
API references and any guides
Never deliberately not document something
If something is subject to change, state that ‘this might change, please don’t rely on it’ Otherwise people will assume that it will stay the same forever.
2. Support articles and blog posts:
Try to keep your own articles up-to-date
If you find inaccurate third party articles, comment or reach out to the authors
Even having a public comment could help.
3. Ad Hoc communication:
Random back and forth between support and solutions engineer, sales team. Not controlled and difficult to make sure that it is “on message”. Hard to know what has been said and committed to.
Try reducing the number of random PDFs that are circling
Store information in central repositories that all the developers can access, not necessarily public.
1. Industry standards
E.g., HTTP headers started becoming downcased as opposed to having capital letters. If you change that accidentally, you can cause other people problems, because they might be looking for specific headers in a case sensitive way, even though the specification officially said you users should treat headers as case insensitive.
Follow industry standards everywhere you possibly can
Shout really loudly if for some reason is that not applicable or if there’s any ambiguity.
2. Observed behavior
”Deliberately call out tripwires in your docs to combat patterns matching: humans are aggressive pattern matchers, we’re creating patterns where are none, and particularly, when it comes to devs, they see the world consistent and want it to be consistent.”
Lots of integrators only look at the HTTPS examples of your docs. It’s often the first place they look and sometimes the only one as well.
Naming is critical (think about names and user test them)
Make sure you show the exceptions in some of the examples
”We need to help our integrators discover when they have made bad assumptions and help them recover from that.”
How breaking is my change?
Empathize with your integrators, be in their shoes
Observe and measure: e.g., rate limit changes, deprecate an endpoint
Dogfood your products
Releasing a potentially breaking change
Pull comms: updating docs or a changelog
Push comms: newsletter or email to integrators
Ack’d comms: wait for a positive response from integrators before rolling out a change
Find the balance between caution & care and product delivery
Can you make the change incremental?
Can you release the change into a test environment (in advance)?
Can you easily roll back if there are unexpected consequences?
Sign up to our Developer Portal Newsletter so that you never miss out on the latest API The Docs recaps and our devportal, API documentation and Developer Experience research publications.