Documentation improvement and support for V2

[ScreamZ]

This is a draft of documentation changes that I will update all along.

Main goal

Currently, Valtio documentation is clumsy in the way that the core API (vanilla) React and utils are mixed.

I'm suggesting splitting core features and adding React Specific, this way the library gets an entry point for a better adoption on NodeJS.

• Rewrite for Core, React and utils
• Add specificity for V2
• Write update instructions/points of interest for migrating to V2

Topics

• Async vs Sync observers
• useProxy
• Detailled subscribe usage, with and without ops + example
• Working on new Menu organisation.

Need some help

• Not sure about the use case for useProxy so I just added the JSdoc to a specified section, maybe you could provide some example ? Is it just about having less import and use the proxy and the snapshot in a single hook?

What we should consider

Currently, we are on a custom NextJS stack with mdx, which is kind of heavy, I rather suggest to move on one of:

• Starlight (with astro)
• Docusaurus
• Nextra
• Gitbook

This way we have access to better built-in components for MDX and a lot of nice tools.

@dai-shi I want your feedback before progressing in a way you're not ok with.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
valtio	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Mar 17, 2024 4:38pm

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

[dai-shi]

Hi, thanks for working on it!

I have a request. Please don't mix a) an improvement for docs that can apply to v1 and b) a new change for docs that is specific to v2.
For a), send a PR to main and we can merge it independent from v2 release.

For doc structure and website, please discuss with @RikuVan and @roguesherlock who built the current docs and website.

My small suggestion is to work on the structure first and the website later. My strong requirement is to separate docs and website, and docs shouldn't depend on any specific tools. Docs should be browsable through GitHub, so we shouldn't rely too much on components and tools that are not available on GitHub.

[dai-shi]

It's a very handy util, but we are still not sure how we should suggest the usage. Our primary hook is useSnapshot and useProxy is a wrapper around it.

[roguesherlock]

Hi, thanks for working on it!

I have a request. Please don't mix a) an improvement for docs that can apply to v1 and b) a new change for docs that is specific to v2. For a), send a PR to main and we can merge it independent from v2 release.

For doc structure and website, please discuss with @RikuVan and @roguesherlock who built the current docs and website.

My small suggestion is to work on the structure first and the website later. My strong requirement is to separate docs and website, and docs shouldn't depend on any specific tools. Docs should be browsable through GitHub, so we shouldn't rely too much on components and tools that are not available on GitHub.

Yeah I agree with daishi here,

1. Any update to the current docs should be a seperate pr so that it can be merged independently
2. we can work on improving the docs/structure for v2 in a separate branch (v2 maybe?)
3. I do agree that the current site is a bit bloated. We haven't discussed this but starlight/shiki for the v2 site would be neat. Probably not important right now though as daishi said we should focus on first writing good content (that's the hard part!).

[dai-shi]

I will work on v2 migration guide.

[dai-shi]

I will work on v2 migration guide.

#878 is something minimal.