Hacker News Reader

Comment by mrbogle | Hacker News Reader

Hey all, we couldn't find exactly what we wanted in a documentation generator, so we wrote our own. Let us know if you have any questions!

View on HN

I appreciate the integrated examples. I wish I had your example generator before I rolled my own.

The documention generator we currently use isn't scaling well with 100+ types and 800+ mutations. It makes the sidebar too unwieldy. It looks like SpectaQL has the same issue. Not sure there's a great solution while keeping to static pages.

Thanks much for the open license. I hope to try it soon.

We might pay for a searchable hosted white label version.

Thanks for the kind words! I wrote most of the enhancements and thought the static and dynamic example support was crucial to have.

Our schema is not as big as yours, but I could see how things could get a bit unwieldy on the navbar. Come on over to the repo and we can work on a solution together - I'm sure there's something we can figure out if we put on our design + product + engineer hats.

Thanks for the feedback! Yeah I can see how it could get out of hand with that many types and mutations. The single page situation would probably break down in that scenario too. We'll think about how it might be able to scale. Feel free to open an issue on the repo and we can work it out together.

What I'd really like to see is a dynamic diagram of the schema, such that when you click on a type it becomes the center of a graph of associations. Then click to view the text docs. The diagram could be a menu / entry point for the text docs. A kind of map to the N-dimensional space.

Ah that would definitely be interesting, you could break out queries / mutations where it is an input, output, or related types where it is a resolver type

We quickly ran into the same issue at Shopify. We've since moved from a flat list into sections by "domains"; within each section is the breakdown by type. You can see it here: https://shopify.dev/docs/admin-api/graphql/reference

Of course this grouping has to be done a little manually. And it's not perfect, but definitely better than the flat alternative. For reference, we have thousands of types.

I could see us adding support for grouping via the "metadata" that would inform the nav bar on how to group and accordion / collapse things. There already is a pattern for grouping in the library that is exemplified in the Query and Mutation carats

Reply on news.ycombinator.com