API Documentation Overhaul
Meshworks
Meshworks shipped a v2 API with 47 breaking changes and no migration guide. Support volume tripled in two weeks. Engineering directors were fielding questions that documentation should have answered. The existing reference was auto-generated from OpenAPI specs — technically accurate, humanly unreadable.
- 01Conducted a content audit: 312 endpoints documented, 0 with usage examples, 14 with incorrect parameter descriptions.
- 02Interviewed 6 integration engineers to map the 12 most common implementation paths through the API.
- 03Rewrote the reference architecture: concepts first, authentication second, endpoints organized by workflow rather than resource type.
- 04Built a migration guide structured as a decision tree: "if your app does X, change Y to Z" — not a changelog.
- 05Added runnable code examples in 4 languages for every endpoint that handles authentication or pagination.
Support tickets referencing documentation dropped 58% in the first month. The migration guide was shared internally by 3 engineering teams as the canonical reference for the v2 transition.
Reorganized from resource-centric to workflow-centric. Developers navigate by what they're trying to do, not what the API is.
The original changelog listed changes chronologically. The rewrite organizes by impact — what breaks, what changes behavior, what is deprecated but still works.
Every endpoint scored on: accuracy, example coverage, error documentation, and cross-reference completeness. Prioritized rewrites by traffic × missing coverage.
