Guides and reference in one portal
Developers do not want a reference site and a separate guides site with separate search. They want to search once and get the answer, whichever kind of page it lives on.
- OpenAPI reference
- Markdown from your repo
- One search index
What is a developer documentation portal?
A developer portal is the single place an integrator goes to learn and to look things up. It combines conceptual guides (how authentication works, how pagination works), task-based tutorials (quickstarts, recipes), and generated API reference from an OpenAPI specification. In TheDocs all three live in one project with shared navigation, shared search and a shared version selector.
- OpenAPI 3.0 and 3.1 reference generated and kept in sync.
- Markdown published from GitHub, GitLab or Azure DevOps.
- Guides, tutorials and reference in one search index.
- Code samples in eight languages, replaceable with your own.
- Documentation versions tied to API versions.
- Generated API changelog with breaking changes flagged.
What a developer portal needs
Most developer portals have the reference and are missing three of the other five.
A quickstart that works
Signup to first successful call in under ten minutes, with the reader's own API key substituted into every sample once they are signed in.
Auth explained once, linked everywhere
One authoritative page on keys, scopes and token lifetimes, referenced from every endpoint rather than half-repeated on each.
Reference that is navigable
Endpoints grouped by tag, deep-linkable down to a single field, searchable across paths, parameters and descriptions.
Errors with remedies
Every error code with its cause and the fix. The single highest-leverage section for reducing integration support load.
A changelog integrators trust
Generated from spec diffs, with breaking changes called out and deprecations carrying a migration path and a date.
Webhooks documented properly
Payload schemas, signature verification, retry behaviour and a replay tool - the parts integrators always have to ask about.
Fitting the way engineering already works
Publish from the pipeline
Documentation that requires a separate manual step after release is documentation that lags release.
- Push Markdown from a repository on merge, with front matter mapped to article metadata.
- Push an OpenAPI spec on tag, with a diff and breaking-change report before publish.
- Scoped API keys for CI, able to publish without read access to private projects.
- Schedule the publish so documentation lands with the deploy, not before or after it.
Being straight about the limits: there are no per-branch preview environments. If content review must happen in pull requests, weigh that before choosing.
Engineers and writers on the same articles
The common failure is a wall: engineers write in the repo, writers edit somewhere else, and the two versions diverge within a quarter.
- Repo-synced articles remain editable in the block editor; edits sync back as a pull request where you want that.
- Prose blocks on generated endpoints survive regeneration, so a writer's explanation is never overwritten by CI.
- Review workflow applies to both paths, so an engineer's push can still require an editor's approval.
- Comments and suggestions work on any article regardless of where it came from.
Related
Questions people ask before they start
Upload your OpenAPI spec and see the portal it produces.
Start free for 14 days. No credit card, no setup fee, and your content is yours to export at any time.
Questions first? Email sales@thedocs.in or call +91 8585953085.