fecqs
diff --git a/Diff for: ‎README.md
+2-2 b/Diff for: ‎README.md
+2-2
diff --git a/Diff for: ‎docs/LINKS.md
+1-1 b/Diff for: ‎docs/LINKS.md
+1-1
diff --git a/Diff for: ‎docs/README.md
+41-35 b/Diff for: ‎docs/README.md
+41-35
diff --git a/Diff for: ‎docs/about-this-documentation.md
+46 b/Diff for: ‎docs/about-this-documentation.md
+46
@@ -125,7 +125,7 @@ The `observer` wrapper around the `TimerView` React component will automatically
 of the component depends on `timer.secondsPassed`, even though this relationship is not explicitly defined. MobX's reactivity system will make sure the component gets re-rendered when _precisely that_ field is updated in the future.
 
 Every event (`onClick` and `setInterval`) invokes an _action_ (`increaseTimer` and `resetTimer` functions) that updates _observable state_ (`secondsPassed` class property).
-Changes in the observable state are propagated precisely to all _computations_ and _side-effects_ (`TimerView` component) that depend on the changes being made.
+Changes in the observable state are propagated precisely to all _computations_ and _side effects_ (`TimerView` component) that depend on the changes being made.
 
 <img alt="MobX unidirectional flow" src="docs/assets/flow2.png" align="center" />
 
@@ -161,6 +161,6 @@ The philosophy and benefits of the mental model provided by MobX are described i
 
 ## Credits
 
-MobX is inspired by reactive programming principles as found in spreadsheets. It is inspired by MVVM frameworks like in MeteorJS tracker, knockout and Vue.js. But MobX brings Transparent Functional Reactive Programming to the next level and provides a stand alone implementation. It implements TFRP in a glitch-free, synchronous, predictable and efficient manner.
+MobX is inspired by reactive programming principles as found in spreadsheets. It is inspired by MVVM frameworks like in MeteorJS tracker, knockout and Vue.js. But MobX brings Transparent Functional Reactive Programming to the next level and provides a standalone implementation. It implements TFRP in a glitch-free, synchronous, predictable and efficient manner.
 
 A ton of credits for [Mendix](https://github.com/mendix), for providing the flexibility and support to maintain MobX and the chance to proof the philosophy of MobX in a real, complex, performance critical applications.
@@ -13,7 +13,7 @@
 -   [rfx-stack](https://github.com/foxhound87/rfx-stack) RFX Stack - Universal App featuring: React + Feathers + MobX
 -   [mobx-reactor](https://github.com/amsb/mobx-reactor) Connect MobX data stores to functional stateless React components with async actions and unidirectional data flow.
 -   [mobx-model](https://github.com/ikido/mobx-model) Simplify mobx data stores that mimic backend models
--   [rx-mobx](https://github.com/chicoxyzzy/rx-mobx) Convert Mobx observables to RxJS and vice versa
+-   [rx-mobx](https://github.com/chicoxyzzy/rx-mobx) Convert MobX observables to RxJS and vice versa
 
 ## More examples
 
 
@@ -1,14 +1,14 @@
 ---
-title: Introduction
-sidebar_label: Introduction
+title: About MobX
+sidebar_label: About MobX
 hide_title: true
 ---
 
 <img src="assets/mobx.png" alt="logo" height="120" align="right" />
 
 # MobX
 
-_Simple, scalable state management_
+_Simple, scalable state management._
 
 [![Discuss on Github](https://img.shields.io/badge/discuss%20on-GitHub-orange)](https://github.com/mobxjs/mobx/discussions)
 [![npm version](https://badge.fury.io/js/mobx.svg)](https://badge.fury.io/js/mobx)
@@ -17,7 +17,7 @@ _Simple, scalable state management_
 
 ---
 
-MobX is made possible by the generosity of the sponsors below, and many [individual backers](http://mobxjs.github.io/mobx/backers-sponsors.html#backers). Sponsoring directly impacts the longevity of this project.
+MobX is made possible by the generosity of the sponsors below, and many other [individual backers](http://mobxjs.github.io/mobx/backers-sponsors.html#backers). Sponsoring directly impacts the longevity of this project.
 
 **🥇 Gold sponsors (\$3000+ total contribution):** <br/>
 <a href="https://mendix.com/"><img src="assets/mendix-logo.png" align="center" width="100" title="Mendix" alt="Mendix" /></a>
@@ -45,7 +45,7 @@ MobX is made possible by the generosity of the sponsors below, and many [individ
 
 ## Introduction
 
-_Anything that can be derived from the application state, should be derived. Automatically._
+_Anything that can be derived from the application state, should be. Automatically._
 
 MobX is a battle tested library that makes state management simple and scalable by transparently applying functional reactive programming (TFRP).
 The philosophy behind MobX is simple:
@@ -55,10 +55,9 @@ The philosophy behind MobX is simple:
         <div class="pic">😙</div>
         <div>
             <h5>Straightforward</h5>
-            <p>With MobX, you write minimalistic, boilerplate free code that captures your intent:
-            Trying to update a record field? Use good old JavaScript assignment.
-            Updating data in an asynchronous process? No special tools are required.
-            The reactivity system will detect all your changes and propagate them out to where they are being used.
+            <p>Write minimalistic, boilerplate free code that captures your intent.
+            Trying to update a record field? Use the good old JavaScript assignment.
+            Updating data in an asynchronous process? No special tools are required, the reactivity system will detect all your changes and propagate them out to where they are being used.
             </p>
         </div>
     </div>
@@ -67,9 +66,9 @@ The philosophy behind MobX is simple:
         <div>
             <h5>Effortless optimal rendering</h5>
             <p>
-                MobX tracks all updates and usages of your data at runtime, building a dependency tree that captures all relations between state and output.
+                All changes to and uses of your data are tracked at runtime, building a dependency tree that captures all relations between state and output.
                 This guarantees that computations depending on your state, like React components, run only when strictly needed.
-                With MobX, there is no need to manually optimize components using error-prone and sub-optimal techniques like memoization and selectors.
+                There is no need to manually optimize components with error-prone and sub-optimal techniques like memoization and selectors.
             </p>
         </div>
     </div>
@@ -103,42 +102,42 @@ class Timer {
         makeAutoObservable(this)
     }
 
-    increaseTimer() {
+    increase() {
         this.secondsPassed += 1
     }
 
-    resetTimer() {
+    reset() {
         this.secondsPassed = 0
     }
 }
 
 const myTimer = new Timer()
 
-// Build a user interface for this app that merely uses the state.
+// Build a "user interface" that uses the observable state.
 const TimerView = observer(({ timer }) => (
-    <button onClick={() => timer.resetTimer()}>Seconds passed: {timer.secondsPassed}</button>
+    <button onClick={() => timer.reset()}>Seconds passed: {timer.secondsPassed}</button>
 ))
 
 ReactDOM.render(<TimerView timer={myTimer} />, document.body)
 
 // Update the 'Seconds passed: X' text every second.
 setInterval(() => {
-    myTimer.increaseTimer()
+    myTimer.increase()
 }, 1000)
 ```
 
-The `observer` wrapper around the `TimerView` React component will automatically detect that rendering
-of the component depends on `timer.secondsPassed`, even though this relationship is not explicitly defined. MobX's reactivity system will make sure the component gets re-rendered when _precisely that_ field is updated in the future.
+The `observer` wrapper around the `TimerView` React component, will automatically detect that rendering
+depends on the `timer.secondsPassed` observable, even though this relationship is not explicitly defined. The reactivity system will take care of re-rendering the component when _precisely that_ field is updated in the future.
 
-Every event (`onClick` and `setInterval`) invokes an _action_ (`increaseTimer` and `resetTimer` functions) that updates _observable state_ (`secondsPassed` class property).
-Changes in the observable state are propagated precisely to all _computations_ and _side-effects_ (`TimerView` component) that depend on the changes being made.
+Every event (`onClick` / `setInterval`) invokes an _action_ (`myTimer.increase` / `myTimer.reset`) that updates _observable state_ (`myTimer.secondsPassed`).
+Changes in the observable state are propagated precisely to all _computations_ and _side effects_ (`TimerView`) that depend on the changes being made.
 
 <img alt="MobX unidirectional flow" src="assets/flow2.png" align="center" />
 
-You can apply this diagram as a conceptual picture to this simple example or any other application using MobX.
+This conceptual picture can be applied to the above example, or any other application using MobX.
 
-To learn about the core concepts of MobX with a larger example, please read [Concepts & Principles](http://mobxjs.github.io/mobx/intro/concepts.html) or take the [10 minute interactive introduction to MobX and React](https://mobx.js.org/getting-started).
-The philosophy and benefits of the mental model provided by MobX are described in detail in the blogs [UI as an afterthought](https://michel.codes/blogs/ui-as-an-afterthought) and [How to decouple state and UI (a.k.a. you don’t need componentWillMount)](https://hackernoon.com/how-to-decouple-state-and-ui-a-k-a-you-dont-need-componentwillmount-cc90b787aa37).
+To learn about the core concepts of MobX using a larger example, check out [The gist of MobX](the-gist-of-mobx.md) section, or take the [10 minute interactive introduction to MobX and React](https://mobx.js.org/getting-started.html).
+The philosophy and benefits of the mental model provided by MobX are also described in great detail in the blog posts [UI as an afterthought](https://michel.codes/blogs/ui-as-an-afterthought) and [How to decouple state and UI (a.k.a. you don’t need componentWillMount)](https://hackernoon.com/how-to-decouple-state-and-ui-a-k-a-you-dont-need-componentwillmount-cc90b787aa37).
 
 ## What others are saying...
 
@@ -154,19 +153,26 @@ The philosophy and benefits of the mental model provided by MobX are described i
 
 ## Further resources and documentation
 
--   [Ten minute, interactive MobX + React tutorial](https://mobx.js.org/getting-started)
--   <i><a style="color: white; background:green;padding:5px;margin:5px;border-radius:2px" href="https://egghead.io/courses/manage-complex-state-in-react-apps-with-mobx">egghead.io course</a></i> (Based on MobX 3)
--   <img src="assets/book.jpg" height="80px"/> [The MobX book](https://books.google.nl/books?id=ALFmDwAAQBAJ&pg=PP1&lpg=PP1&dq=michel+weststrate+mobx+quick+start+guide:+supercharge+the+client+state+in+your+react+apps+with+mobx&source=bl&ots=D460fxti0F&sig=ivDGTxsPNwlOjLHrpKF1nweZFl8&hl=nl&sa=X&ved=2ahUKEwiwl8XO--ncAhWPmbQKHWOYBqIQ6AEwAnoECAkQAQ#v=onepage&q=michel%20weststrate%20mobx%20quick%20start%20guide%3A%20supercharge%20the%20client%20state%20in%20your%20react%20apps%20with%20mobx&f=false) by Pavan Podila and Michel Weststrate.
--   Videos:
-    -   [Introduction to MobX & React in 2020](https://www.youtube.com/watch?v=pnhIJA64ByY) - 17m by Leigh Halliday.
-    -   [ReactNext 2016: Real World MobX](https://www.youtube.com/watch?v=Aws40KOx90U) - 40m [slides](https://docs.google.com/presentation/d/1DrI6Hc2xIPTLBkfNH8YczOcPXQTOaCIcDESdyVfG_bE/edit?usp=sharing)
-    -   [Practical React with MobX](https://www.youtube.com/watch?v=XGwuM_u7UeQ). In depth introduction and explanation to MobX and React by Matt Ruby on OpenSourceNorth (ES5 only) - 42m.
-    -   [MobX and the unique symbiosis of predictability and speed](https://www.youtube.com/watch?v=NBYbBbjZeX4&list=PL8sJahqnzh8JJD7xahG5zXkjfM5GOgcPA&index=21&t=0s) - HolyJS 2019 conf, 59 min
-    -   [Talk: State Management Is Easy, React Amsterdam 2016 conf](https://www.youtube.com/watch?v=ApmSsu3qnf0&feature=youtu.be) ([slides](https://speakerdeck.com/mweststrate/state-management-is-easy-introduction-to-mobx))
--   [MobX awesome list](https://github.com/mobxjs/awesome-mobx#awesome-mobx)
+-   [10 minute interactive introduction to MobX and React](https://mobx.js.org/getting-started)
+-   [Egghead.io course, based on MobX 3](https://egghead.io/courses/manage-complex-state-in-react-apps-with-mobx)
+
+### The MobX book
+[<img src="assets/book.jpg" height="80px"/> ](https://books.google.nl/books?id=ALFmDwAAQBAJ&pg=PP1&lpg=PP1&dq=michel+weststrate+mobx+quick+start+guide:+supercharge+the+client+state+in+your+react+apps+with+mobx&source=bl&ots=D460fxti0F&sig=ivDGTxsPNwlOjLHrpKF1nweZFl8&hl=nl&sa=X&ved=2ahUKEwiwl8XO--ncAhWPmbQKHWOYBqIQ6AEwAnoECAkQAQ#v=onepage&q=michel%20weststrate%20mobx%20quick%20start%20guide%3A%20supercharge%20the%20client%20state%20in%20your%20react%20apps%20with%20mobx&f=false)
+
+Created by [Pavan Podila](https://twitter.com/pavanpodila) and [Michel Weststrate](https://twitter.com/mweststrate).
+
+### Videos
+-   [Introduction to MobX & React in 2020](https://www.youtube.com/watch?v=pnhIJA64ByY) by Leigh Halliday, _17min_.
+-   [ReactNext 2016: Real World MobX](https://www.youtube.com/watch?v=Aws40KOx90U) by Michel Weststrate, _40min_, [slides](https://docs.google.com/presentation/d/1DrI6Hc2xIPTLBkfNH8YczOcPXQTOaCIcDESdyVfG_bE/edit?usp=sharing).
+-   [OpenSourceNorth: Practical React with MobX (ES5)](https://www.youtube.com/watch?v=XGwuM_u7UeQ) by Matt Ruby, _42min_.
+-   [HolyJS 2019: MobX and the unique symbiosis of predictability and speed](https://www.youtube.com/watch?v=NBYbBbjZeX4&list=PL8sJahqnzh8JJD7xahG5zXkjfM5GOgcPA&index=21&t=0s) by Michel Weststrate, _59min_.
+-   [React Amsterdam 2016: State Management Is Easy](https://www.youtube.com/watch?v=ApmSsu3qnf0&feature=youtu.be) by Michel Weststrate, _20min_, [slides](https://speakerdeck.com/mweststrate/state-management-is-easy-introduction-to-mobx).
+-   {🚀} [React Live 2019: Reinventing MobX](https://www.youtube.com/watch?v=P_WqKZxpX8g) by Max Gallo, _27min_.
+
+And an all around [MobX awesome list](https://github.com/mobxjs/awesome-mobx#awesome-mobx).
 
 ## Credits
 
-MobX is inspired by reactive programming principles as found in spreadsheets. It is inspired by MVVM frameworks like in MeteorJS tracker, knockout and Vue.js. But MobX brings Transparent Functional Reactive Programming to the next level and provides a stand alone implementation. It implements TFRP in a glitch-free, synchronous, predictable and efficient manner.
+MobX is inspired by reactive programming principles as found in the spreadsheets. It is inspired by MVVM frameworks like MeteorJS tracker, knockout and Vue.js, but MobX brings _Transparent Functional Reactive Programming_ to the next level and provides a standalone implementation. It implements TFRP in a glitch-free, synchronous, predictable and efficient manner.
 
-A ton of credits for [Mendix](https://github.com/mendix), for providing the flexibility and support to maintain MobX and the chance to proof the philosophy of MobX in a real, complex, performance critical applications.
+A ton of credits goes to [Mendix](https://github.com/mendix), for providing the flexibility and support to maintain MobX and the chance to proof the philosophy of MobX in a real, complex, performance critical applications.
@@ -0,0 +1,46 @@
+---
+title: About this documentation
+sidebar_label: About this documentation
+hide_title: true
+---
+
+<script async type="text/javascript" src="//cdn.carbonads.com/carbon.js?serve=CEBD4KQ7&placement=mobxjsorg" id="_carbonads_js"></script>
+
+# About this documentation
+
+It follows the principle that the most commonly used concepts are
+introduced before specialized information. This applies to the headings in the table
+of concepts as well as the pages under those headings.
+
+We've marked the sections and concepts that are more advanced with the {🚀} marker. You likely won't have to understand them until you will have a special use case, and can use MobX very effectively without knowing about them. Feel free to skip them and move on to the next section!
+
+The documentation has been rewritten for MobX 6. For older versions of MobX, it can be found [here](https://github.com/mobxjs/mobx/tree/mobx4and5/docs).
+All the principles are the same, and the API is largely the same. The main difference is that before MobX 6, [decorators](https://github.com/mobxjs/mobx/blob/mobx4and5/docs/best/decorators.md) were the recommended syntax to write MobX enhanced classes.
+
+## Guided tour
+
+To get an overall idea of how to use MobX with React, read through the current _Introduction_ heading, in particular [The gist of MobX](the-gist-of-mobx.md) section.
+It will introduce you to the most important principles, API's and how they relate.
+You should be ready to use MobX once you read this!
+
+Here are a few suggestions about the next things to check out:
+
+-   Try the [10 minute interactive introduction to MobX and React](getting-started.html)
+
+-   [React integration](react-integration.md)
+
+-   [`makeObservable` / `makeAutoObservable`](observable-state.md)
+
+-   Learn about [actions](actions.md), which includes a discussion on asynchronous actions
+
+-   The basics of [computeds](computeds.md)
+
+-   Read about [`autorun`](reactions.md#autorun), if only because it's used in the examples
+
+-   To get an idea on how to organize your application's data stores, check out [Defining data stores](defining-data-stores.md)
+
+-   If the behavior of MobX confuses you, it's useful to check out [Understanding reactivity](understanding-reactivity.md)
+
+-   Get a [quick overview of the API](api.md), also linked in the top navigation bar
+
+This should give you a good understanding of the day-to-day uses of MobX. There is plenty more available for you to read at your own leisure.