While implementing https://github.com/wasp-lang/wasp/pull/2068, I ended up somewhat modifying sidebar by collapsing by default most of the top level categories (all except for Getting Started).
This is in contract to what we currently have, which is all categories expanded and not nearly fitting into the screen.
We couldn't all agree on how to go about this, with one side of the argument being that it should all be open for discoverability, while the other was that it should all be collapsed in order to facilitate easier higher-level navigation.
I found others split like this:
All expanded, not fitting into the screen: Vue, Tailwind, Astro
All collapsed: Laravel, Remix, ~Next
In between: Svelte, React
So it seems like there is no dominant side.
I wanted to propose a middle ground: leave expanded that which we want them to focus on opening the docs, and leave collapsed the rest. So "getting started" part, maybe tutorial or basics.
Better categories
It seems to me like the current categories became a bit overgrown.
I suggest that instead of Data Model, Authentiation, Project Setup, and Advanced Features, we go with two top-level categories: Basics and Advanced (or Basic Features and Advanced Features), where we would cover all the Wasp features with their API references, like following (this is just a general idea, details are malleable):
We mostly have all these materials and pages, we just need to shuffle a couple things around.
The only thing I found obviously missing is the page about Pages and Routes -> interesting but we don't seem to have a dedicate piece of docs for Pages and Routes, except for the part of the tutorial! I opened an issue for this here: https://github.com/wasp-lang/wasp/issues/2072 .
This issue is taking about two things really that are not necessarily super connected, which is expanded or not, and then category organization, so they could be handled separately.
Mostly collapsed vs mostly expanded
While implementing https://github.com/wasp-lang/wasp/pull/2068, I ended up somewhat modifying sidebar by collapsing by default most of the top level categories (all except for Getting Started).
This is in contract to what we currently have, which is all categories expanded and not nearly fitting into the screen.
We couldn't all agree on how to go about this, with one side of the argument being that it should all be open for discoverability, while the other was that it should all be collapsed in order to facilitate easier higher-level navigation.
I found others split like this:
So it seems like there is no dominant side.
I wanted to propose a middle ground: leave expanded that which we want them to focus on opening the docs, and leave collapsed the rest. So "getting started" part, maybe tutorial or basics.
Better categories
It seems to me like the current categories became a bit overgrown.
I suggest that instead of
Data Model,Authentiation,Project Setup, andAdvanced Features, we go with two top-level categories:BasicsandAdvanced(orBasic FeaturesandAdvanced Features), where we would cover all the Wasp features with their API references, like following (this is just a general idea, details are malleable):We mostly have all these materials and pages, we just need to shuffle a couple things around.
The only thing I found obviously missing is the page about Pages and Routes -> interesting but we don't seem to have a dedicate piece of docs for Pages and Routes, except for the part of the tutorial! I opened an issue for this here: https://github.com/wasp-lang/wasp/issues/2072 .
This issue is taking about two things really that are not necessarily super connected, which is expanded or not, and then category organization, so they could be handled separately.