I am excited to work on this , Could you please assign it to me?

This is like an umbrella issue. So, please create a sub task and assign yourself.

Hi, can I take the first sub task? Fix typo, grammar, and/or expressions (please file a PR)

Does this involve reviewing the readme.md and other md files?

Does this involve reviewing the readme.md and other md files?

Basically, all docs/*.md files.

can I take the first sub task?

Sorry for confusion. I meant sub tasks are more granular ones. Unless many contributors work conflict each other, it's not so important. See #90 for example.

In other words, please go ahead.

I guess this is the best place to discuss this for now :) for context #221 (comment) #228 (review)

So first answer to the question for documentation of RESET symbol:

• https://github.com/JLarky/jotai/blob/new-docs/docs/guides/resettable.md#derived-atom-with-reset-symbol
• https://github.com/JLarky/jotai/blob/new-docs/docs/api/utils.md#RESET

Now the overall idea behind the new-docs branch:

• I have split docs into three categories: API, guides, introduction
• introduction will explain basic concepts, talk about async, and comparison with zustand/recoil
• guides will contain help on how to use jotai in some particular scenarios: nextjs, typescript, devtools; and how to implement some of the patterns: persistence, resettable atoms
• and API describes APIs each bundle provides which consists of type (or some other way to display function signature), what arguments it takes, etc. and some small examples, examples here I think should be as small as possible so it will serve as a reference instead of the whole working application, but I think it's OK for API references to duplicate some of the text or examples that could be already there in guides or introduction

So now back to resettable atoms :)

It's probably not a core concept, so it doesn't need an article in the introduction, but that's a pattern that could be described in the guide. Then guide has links to API reference and API reference has links back to guide if someone needs more information.

And back to the overall idea :) I like how resettable atoms are documented in this branch and I think it makes sense to rewrite docs so they fall in line with that style

• introduction/async.md looks OK to me
• introduction/comparison.md looks OK to me
• introduction/showcase.md looks OK to me
• introduction/core.md needs to read more like introduction into concepts and less like API reference
• api/devtools.md probably OK?
• api/optics.md probably OK for now, but add function types
• api/immer.md probably OK for now, but add function types
• api/utils.md I only done with atomWithReset/useResetAtom/RESET there, other apis need to be described in similar style
• api/core.md needs to read more like like API reference and less like introduction into concepts
• guides/typescript.md looks OK to me
• guides/nextjs.md looks OK to me
• guides/persistence.md looks OK to me
• guides/debugging.md needs to read more like guide on debugging and less like API reference
• guides/resettable.md this and persistence is how I think guides should look

p.s. I tried to setup Docusaurus for the docs so that it will be faster to preview changes without having to upload it to GitHub first. It turned out to be not as easy as I was thinking :) format of the links changes, you need to add some random metadata to the markdown for it to work properly :) I was kind of expecting for it to just magically work :) this part might be relevant since the more links that we add to docs (as I did for reset stuff because before that there was just one link to ./async.md) the more you would have to redo once you are using some document generator :)

@JLarky I like your idea of three categories. You can take the lead for the initial draft. That would be really helpful.

(p.s. you want to join the pmndrs discord and discuss with others?)

Hoping @JLarky 's work is still in progress.

Yeah, please create it as is. It would be nice if you could include the check list to show what's done and what's incomplete.
No situation is changed for the site. We should move forward without it for now.

I have pushed my drafts to https://github.com/JLarky/jotai/commits/new-docs-wip so that if everyone wants to continue the work they could maybe salvage some of it :) TODO has a list of things that I was going to fix.

The main idea behind WIP was to separate core.md into just API reference and introduction into jotai (and overall atomic datastores) concepts, and creating a separate guide on how to use jotai scope. As for core.md I wrote some of it :) but I wasn't happy with what I got and just overall I think you can feel that it wasn't written by one person :) and scope.md I just created a file and didn't write anything there yet, but I was sure that it would be good to write it in a style similar to docs/guides/persistence.md as in "here are few patters how to use jotai scope with examples" :)

The work #280 by @JLarky is merged.
We still need to improve them.
Anyone volunteer please?