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.
11 guides in 5 topics. Every guide compares its approaches and shows the output its commands printed.
- Publish reference docs 2
- Ship docs with the code 3
- Answer questions over your docs 3
- Run developer relations 2
- Measure and audit developer experience 1
Publish reference docs 2 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.
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.
Ship docs with the code 3 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 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 2 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.
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.
Measure and audit developer experience 1 guide
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.
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.