Part 11 of 12 – Conversation Intelligence Platform series Back to Part 1
Most API documentation in telecoms is a reference dump. A list of endpoints. Parameters, types, response codes. If you’re lucky, an example. If you’re very lucky, an example that actually works.
This is not adequate. A reference is useful when you know what you’re looking for. It is nearly useless when you’re trying to understand how something works, why it works that way, or how to combine capabilities to achieve something real. Developers who hit a reference dump when trying to figure out a new platform spend the first hour reading the same three sentences over and over and then go to find someone to ask. That’s a failure of documentation design, not developer competence.
The restructured docs site at docs.simwood.com is built on a different principle: reference is for lookup, guides are for learning. They are different things and should be written, maintained, and presented as different things.
The structure separates the two cleanly.
Platform-level guides cover things true across all services: how authentication works, how the gateway model works, how versioning and deprecation work, what error conventions to expect. These don’t belong to any single service – they’re the foundation. You read them once, early.
Per-service structure gives each service its own section: a service overview (what it does, when to use it), narrative guides covering the core workflows and patterns, an API reference generated directly from the live OpenAPI spec, and code examples. The narrative guides are hand-authored; the reference is auto-generated. Both are updated when the service changes – the reference automatically, the guides by the team responsible for the service.
The principle that drives this split: if a piece of documentation is explaining why something works the way it does, it’s a guide. If it’s specifying a parameter name and its type, it’s reference. Mixing the two produces something that’s bad at both.
The interactive explorer is worth spending a moment on, because it changes how you work with documentation.
Every service in the docs portal is served via Scalar – a modern API reference UI with a live “try it out” capability. You enter your API key directly into the explorer, choose an endpoint, fill in the parameters, and send the request. The response comes back in the browser. You don’t need to open a terminal, construct a curl command, or paste values between windows. You can explore a new endpoint in thirty seconds.
This sounds like a quality-of-life detail. It isn’t. The gap between “I can read what this endpoint does” and “I have seen this endpoint work against my actual account” is enormous in terms of developer confidence. Reducing that gap to thirty seconds changes how quickly new developers get productive and how much time the support team spends answering questions the docs should have answered already.
Real keys, real requests, real responses, in the browser, without setup. That’s the bar.
The technical implementation reflects the independent service architecture described in Part 8. Each service exposes its own OpenAPI spec at /{service}/{version}/openapi.json. The spec is the authoritative contract for that service, owned by the team responsible for it, published automatically on merge. The documentation portal reads the live spec URL rather than a copy – which means the reference is always in sync with what’s actually deployed. The usual failure mode for API documentation – it describes a version of the API that no longer quite matches what’s running – is eliminated.
Adding a new service to the docs portal is a single entry in the service registry file. No restructuring required.
We’re not writing this post to claim the docs are perfect. We’ve historically been terrible at documentation and our customers have forgiven us more often than we deserved. What we’re committing to is the principle: documentation is a product. It gets investment, it gets maintained, it has ownership. The alternative – reference dumps six months out of date, no narrative guidance at all – isn’t where we’re going.
Developers talk about documentation. Not in formal surveys – in Slack, on community forums, in comments on posts like this one. “The docs are actually good” is a competitive differentiator in the developer tools market, and it’s one that takes sustained commitment rather than a single sprint. We’re sustaining it.
Previous: Part 10 – Deprecation as a feature
Next: Part 12 – Internal documentation that actually gets used
