GraphQL Docs: Beyond the Schema
summary
Highnote embeds Apollo Studio as an in-doc API Explorer tied to a test environment so queries execute live, and code samples are executable snippets that run without leaving the docs. About 800 snippets exist; a GitHub Action plus a webhook to Slack reduces pre-release snippet breakage from ~9–10% to 0%. Docs live in HighGraph with a custom frontend, schema reviews and docs-as-code workflows, and docs-testing tools (Doc Detective) validate examples and catch regressions before users hit them.
AI-written summary · about
chapters (10)
- 0:00Why docs matter
- 3:08GraphQL self-documenting
- 5:57Scaling API references
- 9:09Beyond the schema tools
- 11:39Interactive API explorers
- 14:32Guides and tutorials
- 16:18Code snippets best practices
- 19:08Maintaining docs automation
- 21:22Testing and collaboration
- 23:16Q&A
related talks
30mGraphQL is no excuse to stop writing docs
31mGraphQL ecosystem walkthrough
26mDocs, Demos and Developer Experience
20mPlaying with Interactive Documentation
23mGraphQL in real life
42mEngineering Documentation
42mDocumentation as an application: enabling interactive content tailored to the user
21mInteractive Documentation at Scale Using MDX & Next.js