Add sequence diagrams to reference docs with Mermaid
Write an OAuth exchange or a webhook round trip as a Mermaid sequence diagram beside the reference page, check it against the spec in CI, and render it in dark mode.
How-to › Section 11
Document and support developers#
Reference docs, guides, docs that ship inside packages, question answering over docs, developer relations, and measuring your own developer experience.
23 guides in 6 topics. Every guide compares its approaches and shows the output its commands printed.
- Publish reference docs 5
- Write guides and quickstarts 2
- Ship docs with the code 4
- Answer questions over your docs 3
- Run developer relations 5
- Measure and audit developer experience 4
Publish reference docs 5 guides
Reference from the spec and the code: Redoc, Scalar, Swagger UI, Mintlify, ReadMe, Stoplight Elements, mkdocs-material (the docgen apidocs target as one generator option), per-language API references (typedoc, pkg.go.dev, Sphinx, phpDocumentor, YARD), try-it consoles, versioned docs, diagrams (Mermaid, the Voxgig diagram utility), and hosting where each language looks.
Choose a renderer for your OpenAPI reference site
Rank your own schemas by what a renderer can get wrong, build the worst with every renderer you can run, score the rest by hand, and publish the table first.
Detect a reference site drifting from its OpenAPI spec
Fail CI when the built reference carries an operation the spec removed, lacks one it added, or shows a deprecated operation as current, and lint the spec first.
Make a Go client reference render correctly on pkg.go.dev
Doc comments in the syntax the Go formatter keeps, examples that run under the right symbol, and a local render check before a tag the module proxy keeps forever.
Organize a large OpenAPI reference by tags and tag groups
Group a 200-operation reference into tags and tag groups that every renderer shows, check each operation is two clicks away, and keep old deep links working.
Write guides and quickstarts 2 guides
Diátaxis structure for APIs, quickstarts that reach a first call in five minutes, task docs, code samples in six languages that do not go stale (tested in CI), changelog-driven migration guides, versioned guides.
Move guides to a new docs toolchain without breaking URLs
Build the redirect map from your sitemap and your logs, crawl every old URL against the new build before the switch, and audit the anchors a redirect cannot carry.
Turn a breaking release changelog into a migration guide
Diff the old and new API descriptions with oasdiff, group the breaks by the work they cause, add before and after code, and ship it with the release candidate.
Ship docs with the code 4 guides
README conventions per registry (npm, pkg.go.dev doc comments, PyPI long description, Packagist, RubyGems, LuaRocks), docstrings and typed signatures generated from the spec, a CHANGELOG inside the package, examples directories that run in CI, and generated READMEs (the sdkgen docs add target and seneca-doc as options against hand-written templates).
Document Seneca plugin message patterns inside the repo
Generate the pattern reference from the running plugin with seneca-doc, ship it in the README, and diff it against seneca.list() to catch messages an option adds.
Generate Go doc comments from OpenAPI descriptions
Generate a Go client with oapi-codegen, OpenAPI Generator, and sdkgen from one document, and count which summaries, descriptions, and examples reached the comments.
Generate Python docstrings and type hints from an API spec
Generate a Python client whose help() text and type hints come from the OpenAPI document, then measure which descriptions survived, are empty, or repeat the name.
Ship a changelog inside your published package
Put the changelog in the published artifact, and check in CI that it ships and that its newest entry matches the version being released.
Answer questions over your docs 3 guides
RAG and search over docs, specs and transcripts: chunking an OpenAPI document so retrieval returns whole operations, embeddings, hybrid search, citations, evaluation against real support tickets, and hosting (podmind as one production example beside LlamaIndex, LangChain, Cloudflare Vectorize, pgvector, Algolia DocSearch, Inkeep, Kapa).
Chunk an OpenAPI document for retrieval
Cut an OpenAPI description into retrieval chunks that are each one complete operation, so a top hit carries the whole parameter table rather than half a schema.
Host docs question answering on Cloudflare Workers
Embed the question with Workers AI, query a Vectorize index filtered to one docs version, and stream the answer with its sources over Server-Sent Events.
Re-index docs on release without serving stale answers
Build a new documentation index per release, promote it in one write, and fail a check whenever the live index was built from an older version than the docs.
Run developer relations 5 guides
Practitioner DevRel: community forums and office hours, changelog communication, sample apps, content calendars with non-vanity metrics, conference talks and speaker coaching (agenda tooling such as conf-agenda as one option), a technical podcast with editorial independence (Fireside as one example beside Software Engineering Daily and The Changelog), DevRel programme set-up and audit, and fractional CTO and developer management routines.
Audit a DevRel program in one week
List every DevRel activity on Monday, replace each count with an outcome from evidence by Thursday, and present a scored report with three changes on Friday.
Build a sample app that developers fork instead of ignore
Build one sample app with a key, a list, a form, and real errors, name its owner and omissions in the README, and link it only to hosts that can run it.
Choose a developer community platform for year one
Score Discord, Discourse, GitHub Discussions, Slack, and Zulip on search, moderation, identity, cost, and export, then commit to one platform for a year.
Run a changelog channel developers read in time
Carry breaking changes to developers by feed, email, chat, and widget, then score the channels by the keys still calling the old shape on the sunset date.
Run developer management routines as a fractional CTO
Set up a weekly update, one-to-ones, an architecture review, a decision log, and an escalation rule that run without you, then check them after a week away.
Measure and audit developer experience 4 guides
DX as a measured thing: time to first successful call, install friction, SDK adoption per language, error rates by endpoint, support ticket taxonomy, scoring error messages with a rubric, running a DX audit of your own SDK (the checklist a Developer Experience consultancy would use, written for you to run), and production-readiness reviews before a launch.
Choose developer experience metrics for your API
Pick a handful of numbers that move when you change something, and leave out the ones that move when marketing runs a campaign.
Run a developer satisfaction survey for your API
Draw the sample from keys that made calls, ask eight questions, and report every segment with the baseline metric behind each low score.
Score your API's error messages with a rubric
Sample fifty real error responses from the log, score each body 0 to 2 on six criteria, and publish the score per endpoint before anyone redesigns the errors.
Write a production-readiness checklist for a new SDK
Write the checklist your team signs before a first public SDK release: an owner and an exit criterion on every item, and a script that fails the items it can read.
Generate the client instead of writing it#
Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.