Zustand docs and website team

[armaandh]

Taking a look at jotai's official docs website, the documentation is clear and very useful. The https://zustand.surge.sh/ website is pretty to look at...but does not offer anything useful or practical in terms of documentation (must go to github for documentation). I propose adopting jotai's wonderful documentation website for Zustand. In otherwords, making zustand's official website have docs available in it. What do you think?

[dai-shi]

anyone volunteer?

jotai website https://jotai.org is done by jotai maintainers,
and valtio website https://valtio.pmnd.rs is done by valtio website team (and I'm less involved.)
It would be nice to have a team like valtio to move forward.

btw, https://zustand.surge.sh/ is obsoleted link, the current url is https://zustand-demo.pmnd.rs/ .

https://docs.pmnd.rs/zustand/ is a place meant to have docs, but it's not maintained.
What I think is good is to organize ./docs in this repo and configure https://docs.pmnd.rs/zustand/ to use it.
related issue: #1008

[chrisk-7777]

I've closed #1549 in favor of #1559

[holgergp]

@chrisk-7777 The link to the docs (now?) seems to be in footer.js. Am I looking at the right one?

[sewera]

I'm not sure what do you mean, but the link to the docs is https://docs.pmnd.rs/zustand/.

The website src code is in pmndrs/website on branch docs.

The docs src code is in this repo in the docs directory.

@dai-shi, I think the website (https://docs.pmnd.rs/zustand/) is not updated to the latest version (from my previous experience, the Next.js cache has to be invalidated/deleted).

[holgergp]

Ah! The docs branch! Thank you! I was looking at main. Sorry!

[dai-shi]

I'm not sure what do you mean, but the link to the docs is https://docs.pmnd.rs/zustand/.

The website src code is in pmndrs/website on branch docs.

The docs src code is in this repo in the docs directory.

@dai-shi, I think the website (https://docs.pmnd.rs/zustand/) is not updated to the latest version (from my previous experience, the Next.js cache has to be invalidated/deleted).

If the problem persists, you may want to open an issue there. I'm not very familiar with how it's working.

[dai-shi]

The typescript guide is getting bigger. Do we have ideas to split it into multiple files? Like for basic usage, advanced usage, for middleware devs, and detailed internals.

Cc @dbritto-dev @sewera @chrisk-7777 @devanshj

[sewera]

I was more in a "I used Redux in the past,
I want to use Zustand for my next project" kind of place.
That's why I didn't mention a tutorial
about migration from Redux to Zustand.

I think it may be a useful addition to the docs.
I found this part of docs useful for that.

From my perspective, as a kind of user mentioned above,
my previous point of the docs being okay as they are stands.

[dai-shi]

Thanks everyone.
To clarify, my original point was actually simple. typescript.md is bigger than other files. If it's not too confusing, it's fine.

Anyways, it has been a good discussion. What should be our action items?

[sewera]

I'm all for the comment about splitting the TS guide to basic and advanced usage (this comment)

[holgergp]

I was more in a "I used Redux in the past, I want to use Zustand for my next project" kind of place. That's why I didn't mention a tutorial about migration from Redux to Zustand.

I think it may be a useful addition to the docs. I found this part of docs useful for that.

From my perspective, as a kind of user mentioned above, my previous point of the docs being okay as they are stands.

As I have used Redux quite extensively in the past, I like the idea of having something dedicated that guides users from known redux concepts and recipes, to the "zustand"-way. Might (or might not )be a good fit for the docs. Might also be nice from a seo point of view.
If I find the time in coming weeks, I could try and scribble something. Even if it is just something to sort my own understandings of the concepts.

[dai-shi]

As I have used Redux quite extensively in the past, I like the idea of having something dedicated that guides users from known redux concepts and recipes, to the "zustand"-way.

It would be super nice! We are open for it.

[Vishrut19]

Hey! How can I contribute to your project?

[dai-shi]

@dbritto-dev @sewera @chrisk-7777 any thoughts?

[sewera]

@Vishrut19 If you meant what do you have to technically do to contribute, look at the CONTRIBUTING.md file at the root of the Zustand repo.

[chrisk-7777]

Thanks for the offer to help out @Vishrut19 ! 🎉

The good news is we reached a point where the core docs are at a place that we felt comfortable releasing them as an actual site. The original list of tasks can be found under this comment above (#1033 (reply in thread))

Of course, there is always room for improvement - there is always spots that can be iterated on and made better.
Unfortunately, at this stage the list of things to do are less clear, however if you're keen to get stuck in there are a few options:

Option 1: Being you have a fresh set of eyes, you may be able to spot introductory issues that we have missed. So you could read the docs from the start and ask the question "is this clear enough for someone new to Zustand to get started?" Are there any assumptions in knowledge, any steps skipped?

Option 2: Pick a page (or collection of pages) and look for general grammar issues, spelling mistakes, or generally unclear explanations.

For option 1, I would encourage raising it here first as a talking point, so we can discuss before jumping into changes, to make sure it all aligns.

For option 2, with any clear grammar/spelling issues, please feel free to open a PR directly.

If you get stuck running the docs locally, sing out, and we'll give you a hand. As sewara mentioned, the CONTRIBUTING file is a great place to get setup.

Thanks again 👍

[dai-shi]

Do we need recipes.mdx? It's originally a copy of the readme.md section and maintained separately.

An idea would be if we have unique descriptions in recipes, move them to guides.

On the other hand, I personally like "recipes" if we have such contents. Something like this in Jotai: https://jotai.org/docs/recipes/atom-creators

[dbritto-dev]

@dai-shi I'm down with that, could help us answering the same question many times. I've been trying to just pointing to my previous answers on discussions and creating some codesandbox demos for people

[dai-shi]

Hi @dbritto-dev, can you work on it please? It has more priority than #1033 (comment) below.

• Move some contents in recipes.mdx that are not duplicated with readme.md to somewhere else in docs/.
• Remove recipes.md

[dbritto-dev]

@dai-shi here you go -> #2085

[dai-shi]

An idea from @pmeaney
#2074 (reply in thread)

[dbritto-dev]

I'm into that

[pmeaney]

@dai-shi @dbritto-dev 🙇 Happy to help if I can. Currently focused on picking up Nextjs (my current learning binge) + Zustand (my upcoming learning binge). I haven't dug into Zustand yet, but the one thing I wanted to suggest was just that markdown data table layout for showing demo examples (similar to KinglyJS's github readme examples)

[pmeaney]

@dai-shi @dbritto-dev
Example idea:
Ask ChatGTP something like this:
A. Please generate a Zustand finite state machine which powers a NextJS UI, for a oauth2 sign-up and sign-in system. (common & important use case for making an app) (Ask for it to elaborate on the main components. Bring them into a project...)

< Nah-- it's out of scope unless it's simple and local B. From here, potentially provided would be Dockerized (docker-compose) templates for underlying systems (redis-- sessions, postgres-- user system), etc. OR local .jsonfile / Window: localStorage property / sqlite. />

Place A & potentially A+B into an example. A--> Codepen. A+B -->github...

__ input above___

C. output to zustand docs: .md demo datatable row: A. diagram, B. live .gif demo, C. code examples: codepen + github repo template

---

Next:

Ask ChatGPT-- How do I integrate my AuthFSM with my ... PrototypeUXPageFSM? ...Make some basic UX functionality: a kanban board? Something like that. Drag & Drop... or an interactive Data visualization...

AuthFSM -> somePrototypeFSM... how do I make them work together yet stay decoupled?

[dbritto-dev]

@pmeaney @armaandh here you go -> #2489

[mcqj]

For the JS developers who don't embrace Typescript, the documentation is difficult to follow.
The norm on most sites seems to be to have the ability to switch examples between JS and TS and it would be a great addition to the documentation.

[dbritto-dev]

@mcqj yeah, we are working on that