Call for document contributors

[dai-shi]

We've been working on docs, but there are more to do.
Now, this is call for document contributors.
If you are interested in improving docs, please volunteer.

Some tasks are:

• Review current docs
• Fix current docs
• Re-organize current docs
• Ideate for adding/deleting more docs
• Discuss with the ideation
• Write docs
• ... and anything you think it would improve

This discussion will be used as a communication channel.
Please feel free to reply to this discussion if you are interested in working on something.

We also appreciate if anyone can take the lead of this "improving docs" project.

Thanks!

[FahadAlothman-fsd]

Hello daishi,
I would be interested in contributing improving the docs.
But I don't have any experience with leading, so if you need any extra hands I'm eager to help.

[dai-shi]

Cool. Thanks! Yeah, let's wait if someone is interested in leading.
Meanwhile, please check what we have now and share what you think requires to improve.

[tomvardasca]

Hello @dai-shi count me in to help on the documentation. I am happy to start reviewing the current examples.
About reorganizing, what approach are you thinking about? Something like the Svelte tutorial?

[dai-shi]

Great! Please go ahead and see the current docs.

About reorganizing, I mean the folder structure under ./docs, like naming files sections and moving contents around.

About Svelte like tutorial, I'm very interested in such a thing. Do you have any experience with it? (Creating such a tutorial is probably a separate project, so I will create other place to discuss later if we decide to move forward.)

[leweyse]

Hello @dai-shi

I'd be happy to contribute to the documentation. I'll start looking for content that could be added or removed.

[dai-shi]

Cool! Please go ahead.
There might be typo, or something difficult to read. We could improve those too.

[lecepin]

+1

[lecepin]

Some small suggestions.

In the directory structure of the document, is it better to put "API" before "GUIDES"?

I feel a little confused when looking at the content in "GUIDES" before understanding the basic information in "API".

[dai-shi]

Thanks for the suggestion.
Yes, we agree. We plan to add "Getting Started" or "Quick Start" to cover basic APIs, before guides. We haven't started it yet, so suggestion and contribution are welcome.

[vasucp1207]

@dai-shi, As a student I will look forward to contributing to this.

[vasucp1207]

we probably need someone to manage this project. meanwhile, please check docs and get familiar with them. feel free to give some suggestions too.

I am happy to manage this project, time to wrap my head through the docs.

[dai-shi]

Sounds great! For now, the priority in this doc project is improving contents (markdown files). We will be improving the web site separately.

[vasucp1207]

@dai-shi, I want to document your course of jotai, as this is very fast-paced course is it a good idea to do this? Should I create an issue for this?

[vasucp1207]

Or should we create an interactive website for this course?

[dai-shi]

This call #1627 is basically to improve our docs gradually. (But, new ideas are also welcome.)
I think something like the egghead course would be a good candidate for #1638.

as this is very fast-paced course

Sorry about that. 😅

[pnodet]

Food for thought.

https://www.100ms.live/blog/jotai-react-state-management

[chann44]

Hello daishi,
I would be interested in contributing improving the docs.

[dai-shi]

Maybe, one idea is to look through unresolved/resolved discussions here and create/extract something for docs?

[chann44]

yeah let's go through all the discussions and then look for what are the things that we can improve
personally i think docs are good but we can change the structure how they are structure like

1. first start with tutorial that just covers the basics
2. then all the concepts that are there
3. and then the guides that we have
   and so on
   so it just easier to navigate the docs

[chann44]

Also we can redo the ui part too

[dai-shi]

yeah let's go through all the discussions and then look for what are the things that we can improve

Sounds great!

personally i think docs are good

Nice to hear that.

but we can change the structure how they are structure like

For the overall structure and the UI, @sandren is responsible entirely.
Let's focus on markdown contents for this work meanwhile.

[sandren]

For the overall structure and the UI, @sandren is responsible entirely. Let's focus on markdown contents for this work meanwhile.

Yes, as the Markdown content is revised and improved, I will continue to reorganize and update the website as necessary. 🙂

[wenq1]

Sometimes it is somewhat mystical. For example, in the focusAtom document, it is mentioned that

focusAtom` returns WritableAtom which means it's possible to change the peopleAtom data.

However, if we get a bit adventurous, and make the dataAtom in the example an atomWithStorage, will a change in the focusAtom automatically allow part of the dataAtom persist to the storage?

I guess there's no way to find out without a reasonable conjecture or a fiddle. So basically the problems with this kind of information insufficiency might be better solved with a "purpose definition" on each utility function, with usage patterns (not just use cases) described in the doc.

[dai-shi]

Sounds like a good idea.

[rainyEra]

I want to become Jotai contributor, but before I start I want to discuss some things.

When you click Core section title you don't see where to go next. The next part would be Basics/Concepts, but all you see is Utilities and Integrations. Can we make Basics section after Core where newbie would learn true beauty of Jotai's derived/composable states? This would make learning process continious, meanwhile learning process is kinda across docs. Learn process would be: Jotai hooks/Composable States (beauty of Jotai) and I would add a topic where docs explains why Jotai atomic model might be better instead of Redux. Comparision don't cover this topic. There is cases where Redux wouldn't be able to solve re-renders problems, when Jotai is super easy to deal with it. Also, there's no section where you could demonstrate Jotai ability to prevent re-renders and how to implement them.

[dai-shi]

Welcome here.
Your points all seem valid to me.

@sandren is responsible for website and docs structure. So, you should be able to discuss with them.

I can review doc contents mainly for correctness. Basically I'm fine to accept any improvements for doc contents.

[rainyEra]

Cool! Sandren, can we make learning process more opinionated by moving some of Guides topics like Composing Atoms, Atoms in atom to Basics section, where a newbie would learn everything in one section? It would be very similliar to Zustand docs. I can help with that and write docs using all of these features =). Thanks in advance.

[sandren]

@rainyEra Thank you for your interest. These are good suggestions. If you want to get started on writing consolidated material for basics and guides, I can reorganize the navigation for a better learning experience. ☺️

[rainyEra]

@rainyEra Thank you for your interest. These are good suggestions. If you want to get started on writing consolidated material for basics and guides, I can reorganize the navigation for a better learning experience. ☺️

@sandren Cool! Can we make a new branch called "new docs" and discuss its structure with other contributors? Also, could you please move Basics section higher? Learning path migth be based on building small app demonstrating Jotai abilities or simply showing examples. I like first idea more, but community should decide.

[dai-shi]

I think we should split atom creators in recipes into multiple md files. #1914 (reply in thread) What do you think?
@sandren @rainyEra @leweyse @tomvardasca @FahadAlothman-fsd ...

[WagnerMoreira]

@dai-shi I'm interested in contributing, do you still need it? do you have a list of things that you need to cover in the docs?

[dai-shi]

Yes, we still need contributors for docs. We don't have smaller tasks other than what is described in this discussion. Basically, we need someone taking the lead. @rainyEra seems to have an idea, so I wonder if they can create some smaller tasks.

@sandren is responsible for website and docs structure.

I can review doc contents mainly for correctness. Basically I'm fine to accept any improvements for doc contents.

[rainyEra]

Let's start our discussion thread here.

@FahadAlothman-fsd @tomvardasca @leweyse @lecepin @vasucp1207 @chann44

We want to restructure docs and I want to collect ideas & hear everyone.

Questions you should answer:

1. Do you know Jotai at a decent level?
2. Would you be able to make example apps (in a codesandbox) with Jotai & Redux on how Jotai is superior to solve re-renders problems & explain it's atomicity model?

Explain here what would you change in a Jotai docs like you are a core developer.

DON'T: I just don't like that docs are not explicitly enough.
DO: Place Basics section higher, so it would come after Core section to make docs more consistent. Add more chapters to show beauty of Jotai, patterns on how to solve re-renders problems & examples how Jotai is superior compared to Redux and etc.

Also, if you are curios enough and have a lot of ideas, you can write new docs structrure if you want to, like:
— Basics
/Initializing an atom.
/Using atom
....
— Advanced
....

[TomHiller-swd]

I'm not sure how far this has advanced but I wanted to mention that "patterns" are the key to documenting Jotai seemingly unlimited capabilities. If the documentation was just the "core" and a brief description of the utilities, everything else could be patterns with live examples that are unit tested with the latest version. I mention this because there are places where, what I believe, are deprecated features such as delayInit are still mentioned but this may be a misunderstanding on my part.

I have found myself reading through the discussions more often than not because dai-shi and other community members are providing excellent examples of how to solve problems but these can be difficult to find as the descriptions do not always reflect the gold within the comments. Additionally, many answers are outdated as they were asked before v2 or continued development has simplified the answer.

Tagging may help deduping examples were terms that often, but not always overlap, like storage and persistence.

[dai-shi]

"patterns" are the key to documenting Jotai

That's my concern too. How can we proceed?

deprecated features such as delayInit are still mentioned

oops, I didn't notice it. it feels like the persistence guide should be rewritten from scratch. #2341

[TomHiller-swd]

How can we proceed?
The more I think about this, I don't know. My original thought was to have basic docs then "document by example" through the use of patterns with in browser editable interactive code playpens. While basic examples would be clear, as complexity increases, the required React boilerplate I feel would be confusing to anyone looking for a quick reference.

[dai-shi]

btw, we have https://tutorial.jotai.org/ which I think still has much room for improvements.