docs: fix image spacing. fix phrasing and various grammar issues (pmn…

…drs#1333)

docs/getting-started/comparison.md

@@ -15,8 +15,9 @@ differences and similarities between each.
 
 ### State Model
 
-There are no big differences between Zustand and Redux. Both are based on
-immutable state model. Also, Redux needs to wrap your app in context providers.
+Conceptually, Zustand and Redux are quite similar, both are based on an
+immutable state model. However, Redux, requires your app to be wrapped in
+context providers; Zustand does not.
 
 ```ts
 import create from 'zustand'
@@ -106,8 +107,8 @@ const countSlice = createSlice({
   initialState: { value: 0 },
   reducers: {
     incremented: (state, qty: number) => {
-      // Redux Toolkit does not mutate the state, it use Immer library behind
-      // scenes allow us to have something called "draft state".
+      // Redux Toolkit does not mutate the state, it uses the Immer library
+      // behind scenes, allowing us to have something called "draft state".
       state.value += qty
     },
     decremented: (state, qty: number) => {
@@ -125,6 +126,8 @@ When it comes to render optimizations within your app, there are no major
 differences in approach between Zustand and Redux. In both libraries it is
 recommended that you manually apply render optimizations by using selectors.
 
+**Zustand**
+
 ```ts
 import create from 'zustand'
 
@@ -151,6 +154,8 @@ const Component = () => {
 }
 ```
 
+**Redux**
+
 ```ts
 import { createStore } from 'redux'
 import { useSelector, useDispatch } from 'react-redux'
@@ -194,8 +199,8 @@ const countSlice = createSlice({
   initialState: { value: 0 },
   reducers: {
     incremented: (state, qty: number) => {
-      // Redux Toolkit does not mutate the state, it use Immer library behind
-      // scenes allow us to have something called "draft state".
+      // Redux Toolkit does not mutate the state, it uses the Immer library
+      // behind scenes, allowing us to have something called "draft state".
       state.value += qty
     },
     decremented: (state, qty: number) => {
@@ -222,8 +227,11 @@ const Component = () => {
 
 ### State Model
 
-There is a major difference between Zustand and Valtio. Zustand is based on
-the immutable state model, while Valtio is based on the mutable state model.
+Zustand and Valtio approach state management in a fundamentally different way.
+Zustand is based on the **immutable** state model, while Valtio is based on the
+**mutable** state model.
+
+**Zustand**
 
 ```ts
 import create from 'zustand'
@@ -237,6 +245,8 @@ const store = create<State>(() => ({ obj: { count: 0 } }))
 store.setState((prev) => ({ obj: { count: prev.obj.count + 1 } })
 ```
 
+**Valtio**
+
 ```ts
 import { proxy } from 'valtio'
 
@@ -248,9 +258,11 @@ state.obj.count += 1
 ### Render Optimization
 
 The other difference between Zustand and Valtio is Valtio makes render
-optimizations through property access. However, with Zustand it is recommended
+optimizations through property access. However, with Zustand, it is recommended
 that you manually apply render optimizations by using selectors.
 
+**Zustand**
+
 ```ts
 import create from 'zustand'
 
@@ -268,6 +280,8 @@ const Component = () => {
 }
 ```
 
+**Valtio**
+
 ```ts
 import { proxy, useSnapshot } from 'valtio'
 
@@ -285,11 +299,12 @@ const Component = () => {
 
 ### State Model
 
-There are two major differences between Zustand and Jotai. The first one is
-Zustand is a single store, while Jotai consists of primitive atoms and allows
-composing them together. The last one is Zustand store is global in memory, but
-Jotai atoms are not (are definitions that do not hold values) and that's why
-you can not use it outside React.
+There are two major differences between Zustand and Jotai. Firstly, Zustand is a
+single store, while Jotai consists of primitive atoms that can be composed
+together. Secondly, a Zustand store is an external store, making it more
+suitable when when access outside of React is required.
+
+**Zustand**
 
 ```ts
 import create from 'zustand'
@@ -311,6 +326,8 @@ const useCountStore = create<State & Actions>((set) => ({
 }))
 ```
 
+**Jotai**
+
 ```ts
 import { atom } from 'jotai'
 
@@ -319,9 +336,11 @@ const countAtom = atom<number>(0)
 
 ### Render Optimization
 
-The other difference between Zustand and Jotai is: Jotai makes render
-optimizations through atom dependency. However, with Zustand it is recommended that you
-manually apply render optimizations by using selectors.
+Jotai achieves render optimizations through atom dependency. However, with
+Zustand it is recommended that you manually apply render optimizations by using
+selectors.
+
+**Zustand**
 
 ```ts
 import create from 'zustand'
@@ -349,6 +368,8 @@ const Component = () => {
 }
 ```
 
+**Jotai**
+
 ```ts
 import { atom, useAtom } from 'jotai'
 
@@ -364,9 +385,11 @@ const Component = () => {
 
 ### State Model
 
-The major difference is the same as Zustand and Recoil is: Recoil depends on
-atom string keys instead of atom object referential identities. Also, Recoil
-needs to wrap your app in a context provider.
+The difference between Zustand and Recoil is similar to that between Zustand and
+Recoil. Recoil depends on atom string keys instead of atom object referential
+identities, additionally, Recoil needs to wrap your app in a context provider.
+
+**Zustand**
 
 ```ts
 import create from 'zustand'
@@ -386,6 +409,8 @@ const useCountStore = create<State & Actions>((set) => ({
 }))
 ```
 
+**Recoil**
+
 ```ts
 import { atom } from 'recoil'
 
@@ -397,10 +422,12 @@ const count = atom({
 
 ### Render Optimization
 
-The other difference between Zustand and Recoil is: Recoil makes render
-optimizations through atom dependency. However, with Zustand it is recommended that you
+Similar to previous optimization comparisons, Recoil makes render optimizations
+through atom dependency. Whereas, with Zustand, it is recommended that you
 manually apply render optimizations by using selectors.
 
+**Zustand**
+
 ```ts
 import create from 'zustand'
 
@@ -425,6 +452,8 @@ const Component = () => {
 }
 ```
 
+**Recoil**
+
 ```ts
 import { atom, useRecoilState } from 'recoil'
 

docs/getting-started/concepts.md

@@ -4,4 +4,6 @@ description:
 nav: 1
 ---
 
-⚠️ This doc is still under construction. https://github.com/pmndrs/zustand/discussions/1033
+<Hint>
+  ⚠️ This doc is still under construction. https://github.com/pmndrs/zustand/discussions/1033
+</Hint>

docs/getting-started/introduction.mdx

@@ -4,20 +4,23 @@ description: How to use Zustand
 nav: 0
 ---
 
-⚠️ This doc is still under construction. https://github.com/pmndrs/zustand/discussions/1033
+<Hint>
+  ⚠️ This doc is still under construction.
+  https://github.com/pmndrs/zustand/discussions/1033
+</Hint>
 
-<p align="center">
-  <img width="600" src="https://github.com/pmndrs/zustand/raw/main/bear.jpg" />
-</p>
+<div class="flex justify-center mb-4">
+  <img src="https://github.com/pmndrs/zustand/raw/main/bear.jpg" />
+</div>
 
-A small, fast and scalable bearbones state-management solution. Has a comfy api based
-on hooks, isn't boilerplatey or opinionated, but still just enough to be explicit
-and flux-like.
+A small, fast and scalable bearbones state-management solution. Zustand has a comfy api based on hooks. It isn't boilerplatey or opinionated, but still has enough to be explicit and flux-like.
 
-Don't disregard it because it's cute. It has quite the claws, lots of time was spent to deal with common pitfalls, like the dreaded [zombie child problem](https://react-redux.js.org/api/hooks#stale-props-and-zombie-children), [react concurrency](https://github.com/bvaughn/rfcs/blob/useMutableSource/text/0000-use-mutable-source.md), and [context loss](https://github.com/facebook/react/issues/13332) between mixed renderers. It may be the one state-manager in the React space that gets all of these right.
+Don't disregard it because it's cute, it has claws! Lots of time was spent to deal with common pitfalls, like the dreaded [zombie child problem](https://react-redux.js.org/api/hooks#stale-props-and-zombie-children), [React concurrency](https://github.com/bvaughn/rfcs/blob/useMutableSource/text/0000-use-mutable-source.md), and [context loss](https://github.com/facebook/react/issues/13332) between mixed renderers. It may be the one state-manager in the React space that gets all of these right.
 
 You can try a live demo [here](https://codesandbox.io/s/dazzling-moon-itop4).
 
+## Installation
+
 ```bash
 npm install zustand
 ```
@@ -38,7 +41,7 @@ const useStore = create((set) => ({
 
 ## Then bind your components, and that's it!
 
-Use the hook anywhere, no providers needed. Select your state and the component will re-render on changes.
+You can use the hook anywhere, without the need of providers. Select your state and the consuming component will re-render when that state changes.
 
 ```jsx
 function BearCounter() {

docs/guides/immutable-state-and-merging.md

@@ -48,7 +48,7 @@ const useCountStore = create((set) => ({
 ```
 
 For complex use cases, consider using some libraries that help with immutable updates.
-You can refer to [Updating nested state object values](./updating-nested-state-object-values.md).
+You can refer to [Updating nested state object values](./updating-state.md#deeply-nested-object).
 
 ## Replace flag