diff --git a/src/content/blog/technical/developer-relations-docs.mdx b/src/content/blog/technical/developer-relations-docs.mdx index 85452a3f..3430cfcd 100644 --- a/src/content/blog/technical/developer-relations-docs.mdx +++ b/src/content/blog/technical/developer-relations-docs.mdx @@ -28,6 +28,8 @@ Engineering owns the API reference, and product owns the changelog. DevRel write When the product changes, the API reference gets updated. Engineering's definition of done requires it. The changelog gets an entry because product runs the release process. The getting-started guide, the code samples, and the tutorial for the old authentication flow update on a slower cycle. Sometimes they do not update at all. +Developers do not see the org chart. They see documentation that contradicts the product. In [Postman's 2024 State of the API report](https://www.postman.com/state-of-api/2024), 39% of developers named inconsistent documentation as their biggest roadblock when working with APIs. + After six months, documentation becomes unreliable. After a year, developers learn to distrust it by default. They go straight to the source code, or they open a support ticket. Once developers lose trust, it is expensive to rebuild. One case study measured this cost for a single stale tutorial. The stale tutorial caused 47 support hours of extra work and three churned customers. Developer community trust took six months to recover. @@ -42,6 +44,8 @@ In 2026, AI coding assistants became the primary consumers of developer document This matters most for DevRel teams. Human developers can compensate for incomplete documentation by drawing on experience and community resources, but an AI coding assistant cannot. It follows the documented path exactly. A stale getting-started guide then produces broken integrations at scale, one for every developer who uses an AI coding assistant to onboard. +The damage also compounds within a single session. An assistant works in steps, and each step builds on what the earlier ones produced. A stale authentication page read at the start becomes an assumption behind every step after it, including the code the assistant finally writes. Nothing later in the session goes back to question it, which is the failure mode [context engineering](/blog/technical/agent-context-engineering) describes. + The feedback loop has also become faster. When a developer follows broken docs, they may debug for a day before filing a support ticket. When an AI coding assistant follows broken docs, the developer sees the error within seconds. Errors now surface more often, and they surface faster. For more on how AI coding assistants consume developer documentation, see [Agent Context Files Explained: AGENTS.md, CLAUDE.md, and llms.txt](/blog/technical/agent-context-files-explained). @@ -54,18 +58,22 @@ Procedural content breaks when the API changes. API changes happen constantly in This gap persists because API changes do not automatically trigger a documentation review. Engineering's release process ends when the code ships. The documentation review is a separate step. It requires someone to remember it and have time to do it. In practice, teams often do this late, or they skip it entirely. +Within procedural content, the risk is not spread evenly. Quickstarts carry the most traffic and the most exposure, because a developer who hits a broken first step usually leaves before becoming a customer. Code samples break whenever the SDK changes, and a sample that does not run casts doubt on every other page. Authentication flows change rarely and break every existing integration when they do. Quickstarts, code samples, and authentication flows need a check on every release. Conceptual pages can wait for a quarterly cycle. + [Documentation drift](/blog/technical/documentation-drift-detection-problem) is a detection problem. Teams rarely discover stale docs through a monitoring system. Instead, they discover stale docs through developer complaints. By the time a support ticket arrives, many other developers have already hit the same broken path. Most of them just move on without reporting it. The documentation versioning problem is related. Every API version you support adds more work to keep docs accurate. A tutorial written for v2 may be partially accurate for v3. But partially accurate documentation is worse than no documentation, because an AI coding assistant follows it literally. See [Documentation Versioning Best Practices for API Teams](/blog/technical/documentation-versioning-maintenance-multiplier) for how teams structure this. ## What the ownership model needs -The fix changes how teams assign responsibility for accuracy. Three things need to be explicit: +The fix changes how teams assign responsibility for accuracy. Four things need to be explicit: **Who owns each piece of documentation.** Each piece needs a named owner. One person owns the getting-started guide, and one team owns the SDK reference. Shared ownership without a named individual equals no ownership at all. **What triggers a documentation review.** An API change, a deprecation, or a new SDK release should each trigger a review. Document these triggers in the same place as the ownership assignments. When a trigger fires, the owner reviews the affected docs. +**Which pages a given change can break.** A trigger only helps if the owner knows what to open. Map which tutorials, quickstarts, and reference pages depend on each endpoint, field, and SDK method. A spreadsheet is enough to start. Then a renamed endpoint immediately names the pages to check. + **How drift is detected when triggers are missed.** Ownership and triggers work only when everyone follows the process. They fail when a change ships without the right people knowing. They also fail when a doc page isn't connected to the code it describes. Automated monitoring compares documentation against the current API spec or codebase. This monitoring closes the gap. This is what [treating documentation like code](/blog/technical/help-center-to-docs-as-code) means in practice. Teams assign explicit ownership. They keep content under version control. They build a process that detects when content diverges from the system it describes.