Move detailed docs to Wiki or gitbook?

[benjaminbojko]

Currently our docs are fragmented across package READMEs and a few topic-specific markdowns.

We might benefit from something like gitbook.com to organize everything in a central place, provide better examples and navigation.

A GitHub Wiki might also be an option, but I find the navigation and feature set harder to navigate.

Any other products out there that might come in handy? E.g. something to generate git pages with based on actual API specs?

[claytercek]

I've seen a lot of love for vitepress and astro's starlight theme lately when it comes to SSG for docs. Both could be written in a top-level docs folder and then published to github pages via actions.

[benjaminbojko]

Both look really interesting! I like the idea of it being on a GH page instead of an external service.

At first glance, vitepress seems a little more feature rich on the code formatting front (that blurred/focused line-highlighter is ✨ ). Do you have a pref between the two?

[claytercek]

Oooo that is a very nifty feature, I didn't notice that.

No strong preferences on my end!

[benjaminbojko]

I would vote for Vitepress then! Could be a nice exercise to try and convert our existing docs. Raises the question of whether that should be its own docs package (or branch?). Currently READMEs are distributed across packages as the main READMEs and topic-specific docs generated automatically using a jsdoc2md script.

I think the autogenerated API docs are great, but I'm not very attached to the current specific implementation. Ultimately, more curated examples/how-tos are most often more helpful than the full docs. Will give it some more thought, but also welcome any additional input.

[claytercek]

Vitepress docs are included in 2.0 release!