This talk was presented at API The Docs Virtual 2022 event series on 16 November. We are glad to present the video recording, slide deck and talk summary below. Enjoy!
Visit the talk listing page for an overview of all presentations!
Developer Experience & Relations at StepZen
”Documentation 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.”
Documentations can also be:
It is an interactive playground HDI for exploring GraphQL APIs. GraphQL APIs rely on a GraphQL schema that can usually be introspected, so computers can read the schema and then extrapolate it in any way they like. A common way is doing this in GraphiQL, which is dynamic documentation because you can interact with the product directly.
GraphiQL is self-documenting but only to a small amount.
GraphiQL is mostly dynamic but lacks space for explanations, the space we need for text, graphics, and videos.
Using static documentation and enhancing them with GraphiQL. Many static documentation generators (e.g. Magidoc, SpectaQL,DociQL, etc.) for GraphQL use the same format and schema as GraphiQL. This also makes updating both static and dynamic documentation easier because they have the same source. Static documentation can be further enhanced with videos, graphics, or more text. You can also embed or put links to GraphiQL in your static documentation.
”So together they are actually a rocket ship, because this way you have static documentation and dynamic documentation all coming from one GraphQL schema. And you can do all three things that you like to do with your API documentation, in this scenario GraphQL, which is describing, explaining, and instructing people how to use a product.”