This talk was presented at API The Docs Virtual 2021 event series on 5 May. We are glad to present the video recording, slide deck and talk summary below. Enjoy!
Visit our talk recaps ToC page for an overview of all presentations!
Empathy
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.
Prevent
”We need to help our integrators stop making bad assumptions.”
How do assumptions develop?
Explicit assumptions
1. Documentation:
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.
Implicit assumptions:
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
Mitigate
”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.
