Notes on making systems
behave in production.
Working notes on building and operating automation, APIs, and integrations. This is not a content programme. It is what we write down after solving something, so we do not have to solve it from scratch again.
- 01
Writing a runbook somebody will actually read
Most runbooks are architecture documents wearing a different hat. A runbook is read by a tired person under pressure, and it should be organised around what broke.
OperationsDocumentationHandover7 min read - 02
What turns an endpoint into an API product
The endpoint is the easy part. Authentication, quota accounting, plans, billing, a dashboard, docs, versioning, error shapes and rate limits are the product.
API productsPlatformDeveloper experience7 min read - 03
Retries that help, and retries that make it worse
Retrying is the default fix for a flaky integration. Applied to the wrong failure it turns one problem into duplicate charges, duplicate emails, and an outage you caused yourself.
ReliabilityIntegrationError handling8 min read - 04
Why your automation fails quietly, and what to do about it
An error page is a gift. The dangerous failures are the ones that produce no error at all, and keep reporting success while nothing happens.
ReliabilityAutomationMonitoring7 min read