GraphQL is no excuse to stop writing docs

on YouTube ↗30m

" summary

GraphQL provides a schema and an introspection query but that only yields a reference, so GraphiQL/Playground/Apollo Studio and similar tools expose types and let users run queries yet they lack installation, authentication, troubleshooting and onboarding content. Use introspection to auto-generate a static API reference and combine it with hand-authored guides, code snippets and FAQs; examples of generators are MagicDoc, DociQL and SpectaQL. Stepson uses schema introspection to federate APIs, showing this hybrid approach works in practice.

AI-written summary · about

" chapters (4)

1. 0:00Start
2. 3:26Documentation is any communicable material that is used to describe, explain or instruct regarding some attributes of an object, system or procedure, such as its parts, assembly, installation, maintenance and use.
3. 23:26Documentation could be both static and dynamic
4. 27:10Authentication Troubleshoot

" related talks

• 35mGraphQL Docs: Beyond the SchemaSarah Sanders · Write the Docs Atlantic 2024
• 26mTrustworthy and Sensible API Docs with GraphQLGaren Torikian · Write the Docs Prague 2017
• 58mGraphQL -- Flexible APIs for Adaptive ClientsBrian Genisio · CodeMash 2018
• 13mGraphQL for people who don’t need itChoon Keat Chew · iOS Conf SG 2020
• 48mGraphQL Is the New SexySergey Pirogov · QA Fest 2018
• 25mGraphQL Docs: Beyond the SchemaSarah Sanders · GraphQLConf 2024
• 22mGraphQL for EveryoneDanielle Man · GraphQL Galaxy 2020
• 23mGraphQL in real lifeRoberto Orgiu · Android Makers 2019