Documentation: A slight revamp of the README, wording, and clearer li…

…nks (#3458)

* docs: Slight clarification on atoms

* docs: Include API in sidebar

* docs: Make the links from the API to usage documentation more clear. Adding links.

* docs: Improve organization and wording of READMEs. Trim GitHub README and point to mobx.js.org.

* Fix an error in my previous change: `override` is an annotation passed to makeObservable. Fixing the spelling of "overriden"→"overridden".

* Reverse my previous edit which had re-ordered the Introduction above Sponsors in the Readme

* Revert my change from the term "transparent functional reactive programming" #3458 (comment)

* Link to MobX book on mention of "transparent functional reactive programming".

* Add missing snapshots to fix CI

* Add changeset

Co-authored-by: Egor Gorbachev <7gorbachevm@gmail.com>

.changeset/red-cups-yell.md

@@ -0,0 +1,6 @@
+---
+"mobx": patch
+"mobx-react": patch
+---
+
+A slight revamp of the README, wording, and clearer links

README.md

@@ -7,13 +7,18 @@ _Simple, scalable state management._
 [![npm version](https://badge.fury.io/js/mobx.svg)](https://badge.fury.io/js/mobx)
 [![OpenCollective](https://opencollective.com/mobx/backers/badge.svg)](docs/backers-sponsors.md#backers)
 [![OpenCollective](https://opencollective.com/mobx/sponsors/badge.svg)](docs/backers-sponsors.md#sponsors)
-
 [![Discuss on Github](https://img.shields.io/badge/discuss%20on-GitHub-orange)](https://github.com/mobxjs/mobx/discussions)
 [![View changelog](https://img.shields.io/badge/changelogs.xyz-Explore%20Changelog-brightgreen)](https://changelogs.xyz/mobx)
 
 ---
 
-> Documentation for older **unsupported** V4/V5 can be [found here](https://github.com/mobxjs/mobx/blob/mobx4and5/docs/README.md), but be sure to read about [current documentation first](https://mobx.js.org/about-this-documentation.html).
+## Documentation
+
+Documentation can be found at **[mobx.js.org](https://mobx.js.org/)**.
+
+---
+
+## Sponsors
 
 MobX is made possible by the generosity of the sponsors below, and many other [individual backers](https://github.com/mobxjs/mobx/blob/main/docs/backers-sponsors.md#backers). Sponsoring directly impacts the longevity of this project.
 
@@ -48,35 +53,36 @@ MobX is made possible by the generosity of the sponsors below, and many other [i
 
 _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).
+MobX is a battle-tested library that makes state management simple and scalable by transparently applying functional reactive programming.
 The philosophy behind MobX is simple:
 
 <div class="benefits">
     <div>
         <div class="pic">😙</div>
         <div>
-            <h5>Straightforward</h5>
-            <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.
+            <h4>Straightforward</h4>
+            <p>Write minimalistic, boilerplate-free code that captures your intent.
+            Trying to update a record field? Simply use a normal JavaScript assignment —
+            the reactivity system will detect all your changes and propagate them out to where they are being used.
+            No special tools are required when updating data in an asynchronous process.
             </p>
         </div>
     </div>
     <div>
         <div class="pic">🚅</div>
         <div>
-            <h5>Effortless optimal rendering</h5>
+            <h4>Effortless optimal rendering</h4>
             <p>
                 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.
+                This guarantees that computations that depend on your state, like React components, run only when strictly needed.
                 There is no need to manually optimize components with error-prone and sub-optimal techniques like memoization and selectors.
             </p>
         </div>
     </div>
     <div>
         <div class="pic">🤹🏻‍♂️</div>
         <div>
-            <h5>Architectural freedom</h5>
+            <h4>Architectural freedom</h4>
             <p>
                 MobX is unopinionated and allows you to manage your application state outside of any UI framework.
                 This makes your code decoupled, portable, and above all, easily testable.
@@ -85,6 +91,8 @@ The philosophy behind MobX is simple:
     </div>
 </div>
 
+---
+
 ## A quick example
 
 So what does code that uses MobX look like?
@@ -127,7 +135,7 @@ setInterval(() => {
 }, 1000)
 ```
 
-The `observer` wrapper around the `TimerView` React component, will automatically detect that rendering
+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` / `setInterval`) invokes an _action_ (`myTimer.increase` / `myTimer.reset`) that updates _observable state_ (`myTimer.secondsPassed`).
@@ -137,49 +145,36 @@ Changes in the observable state are propagated precisely to all _computations_ a
 
 This conceptual picture can be applied to the above example, or any other application using MobX.
 
-To learn about the core concepts of MobX using a larger example, check out [The gist of MobX](https://mobx.js.org/the-gist-of-mobx.html) section, 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 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).
-
-<div class="cheat"><a href="https://gum.co/fSocU"><button title="Download the MobX 6 cheat sheet and sponsor the project">Download the MobX 6 cheat sheet</button></a></div>
-
-## What others are saying...
-
-> Guise, #mobx isn't pubsub, or your grandpa's observer pattern. Nay, it is a carefully orchestrated observable dimensional portal fueled by the power cosmic. It doesn't do change detection, it's actually a level 20 psionic with soul knife, slashing your viewmodel into submission.
-
-> After using #mobx for lone projects for a few weeks, it feels awesome to introduce it to the team. Time: 1/2, Fun: 2X
+## Getting started
 
-> Working with #mobx is basically a continuous loop of me going “this is way too simple, it definitely won’t work” only to be proven wrong
-
-> I have built big apps with MobX already and comparing to the one before that which was using Redux, it is simpler to read and much easier to reason about.
-
-> The #mobx is the way I always want things to be! It's really surprising simple and fast! Totally awesome! Don't miss it!
+To learn about the core concepts of MobX using a larger example, check out **[The gist of MobX](https://mobx.js.org/the-gist-of-mobx.html)** page, 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 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).
 
-## Further resources and documentation
+## Further resources
 
--   [MobX cheat sheet (also sponsors the project)](https://gum.co/fSocU)
+-   The [MobX cheat sheet](https://gum.co/fSocU) (£5) is both useful and sponsors the project
 -   [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 awesome list](https://github.com/mobxjs/awesome-mobx#awesome-mobx) – a long list of MobX resources and example projects
 
 ### The MobX book
 
-[<img src="https://mobx.js.org/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)
+<a href="https://www.packtpub.com/product/mobx-quick-start-guide/9781789344837"><img src="https://mobx.js.org/assets/book.jpg" height="120px" /></a>
 
-Created by [Pavan Podila](https://twitter.com/pavanpodila) and [Michel Weststrate](https://twitter.com/mweststrate).
+The **[MobX Quick Start Guide](https://www.packtpub.com/product/mobx-quick-start-guide/9781789344837)** ($24.99) by [Pavan Podila](https://twitter.com/pavanpodila) and [Michel Weststrate](https://twitter.com/mweststrate) is available as an [ebook](https://www.packtpub.com/product/mobx-quick-start-guide/9781789344837), [paperback](https://www.amazon.com/MobX-Quick-Start-Guide-Supercharge/dp/1789344832), and on the [O'Reilly platform](https://www.oreilly.com/library/view/mobx-quick-start/9781789344837/) (see [preview](https://books.google.com/books?id=ALFmDwAAQBAJ&printsec=frontcover#v=onepage&q&f=false)).
 
 ### 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).
--   [CityJS 2020: MobX, from mutable to immutable, to observable data](https://www.youtube.com/watch?v=ZHxFrbK3VB0&feature=emb_logo) by Michel Weststrate, _30min_.
--   [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).
+-   [Introduction to MobX & React in 2020](https://www.youtube.com/watch?v=pnhIJA64ByY) by Leigh Halliday, _17 min_.
+-   [ReactNext 2016: Real World MobX](https://www.youtube.com/watch?v=Aws40KOx90U) by Michel Weststrate, _40 min_, [slides](https://docs.google.com/presentation/d/1DrI6Hc2xIPTLBkfNH8YczOcPXQTOaCIcDESdyVfG_bE/edit?usp=sharing).
+-   [CityJS 2020: MobX, from mutable to immutable, to observable data](https://youtu.be/sP7dtZm_Wx0?t=27050) by Michel Weststrate, _30 min_.
+-   [OpenSourceNorth: Practical React with MobX (ES5)](https://www.youtube.com/watch?v=XGwuM_u7UeQ) by Matt Ruby, _42 min_.
+-   [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, _59 min_.
+-   [React Amsterdam 2016: State Management Is Easy](https://www.youtube.com/watch?v=ApmSsu3qnf0&feature=youtu.be) by Michel Weststrate, _20 min_, [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, _27 min_.
 
 ## Credits
 
-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.
+MobX is inspired by reactive programming principles, which are for example used in spreadsheets. It is inspired by model–view–viewmodel frameworks like [MeteorJS's Tracker](https://docs.meteor.com/api/tracker.html), [Knockout](https://knockoutjs.com/) and [Vue.js](https://vuejs.org/), but MobX brings _transparent functional reactive programming_ (TFRP, a concept which is further explained in the [MobX book](https://www.packtpub.com/product/mobx-quick-start-guide/9781789344837)) 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 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.
+A ton of credit goes to [Mendix](https://github.com/mendix), for providing the flexibility and support to maintain MobX and the chance to prove the philosophy of MobX in a real, complex, performance critical applications.