docs: Add README.md to the docs folder, and update REACTIVITY.md

Brocco · Apr 22, 2021 · 93111d7 · 93111d7
1 parent 37e308b
commit 93111d7
Show file tree

Hide file tree

Showing 4 changed files with 34 additions and 14 deletions.
diff --git a/docs/CHEATSHEET.md → docs/CHEAT_SHEET.md b/docs/CHEATSHEET.md → docs/CHEAT_SHEET.md
diff --git a/docs/REACTIVITY.md b/docs/REACTIVITY.md
@@ -1,21 +1,21 @@
 # Qoot Reactivity
 
-Qoot is a component level reactive, template level reconciliation rendering framework.
+Qoot is a component-level reactive, template-level reconciliation, rendering framework.
 
-All frameworks face the problem of knowing when a component should be re-rendered. There are many different approaches to this problem. Generally the solutions fall into these categories:
+All frameworks face the problem of knowing when a component should be re-rendered. There are many different approaches to this problem. Generally, the solutions fall into these categories:
 
-- **Reactive:** Reactive frameworks understand the relationships between source of state, and usage of state. For example data is store on this object property and when the property changes then these listeners are invoked which in turn update the UI. Generally reactive frameworks need some sort of subscription system which notifies interest in data and instructions on where the changes should be delivered. (Example would be RxJs.)
-  - **Binding level:** Reactive system can further be subdivide into system where the change is delivered directly to a specific DOM property. Such a system would be very fine grained.
-  - **Component level:** In contrast to binding level reactive system, a component level reactivity means that a change to data notifies that the component is dirty. At some later point in time the component is fully re-rendered (we don't actually know which binding needs to be changed so we re-render the whole component.)
-- **Structured state:** Stores the state of the application in a well know location which is guarded for writes. Any writes result in application view to be considered dirty and the view is than re-rendered with the new state. (Example would be redux pattern.)
-- **Unstructured state:** State is stored in memory heap and any execution of the code assumes that there was a write and invalidates the view, scheduling it for re-rendering.
+- **Reactive:** Reactive frameworks understand the relationships between the source of state and usage of state. For example, data is stored on an object property. If the property changes, then subscribers are notified, which in turn updates the UI. Generally speaking, reactive frameworks need some form of a subscription system that notifies interest in data. Once subscriber is notified of change to date, the subscriber delivers the change to the UI. (An example would be RxJs.)
+  - **Binding level:** Reactive system can be subdivided into a system where the change is delivered directly to a specific DOM property. Such a system would be fine-grained (binding level.)
+  - **Component level:** In contrast to a binding level reactive system, a component level reactivity would deliver the change to the component (rather then to a specific binding in the component's template). The delivery of this change would mark the component as dirty. Marking component dirty means that at a later point in time, the component is fully re-rendered (we don't actually know which binding needs to be changed, so we re-render the whole component.)
+- **Structured state:** Stores the state of the application in a well-known location. The system guards state against data writes. Any writes to the state result in the whole application view being considered dirty. The reason why the whole application is dirty is because the system does not know which data will end up where, and so it has to assume that any component could be changed as a result of the system write. (Example would be a redux pattern.)
+- **Unstructured state:** state is stored in memory heap, and any execution of the code assumes that there was a property write which necessitates the invalidation of the view. This schedules the view for re-rendering. (Example would be Angular with zone.js)
 
-The advantage of reactive systems is that we know when a listener needs to be updated (instead of updating the whole app). The down side is that we need to set up and clean up the listeners. The listeners are usually function closures which close over a component instance and its template. Setting up these kinds of listeners would force code to be downloaded too early defeating the goal of Qoot to only download the immediately necessary code.
+The advantage of reactive systems is that the system knows when a subscriber needs to be updated (instead of updating the whole app.) The downside is that the system needs to set up and clean up the subscriptions. The subscriptions are usually function closures that close over a component instance and its template. Setting up these kinds of subscriptions would force code to be downloaded too early, defeating the goal of Qoot only to download the immediately necessary code.
 
-Qoot takes the approach of storing application state in services. Components subscribe to services to get notified of service state change. The subscription creates a component level reactive system. The subscription system gives Qoot knowledge to know when and which component should be invalidated and scheduled for re-rendering when the data store changes. This solves the issue of having to re-render the whole app on any state change. Knowing which components subscribe to which service allows Qoot to only download and render the relevant components.
+Qoot takes a different approach to setting up the subscriptions. Qoot stores application state in services. Components subscribe to services to get notified of service state change. The subscription creates a component-level reactive system. The subscription system gives Qoot knowledge to know when and which component should be invalidated and scheduled for re-rendering when the data store changes. This solves the issue of having to re-render the whole app on any state change. Knowing which components subscribe to which service allows Qoot only to download and render the relevant components.
 
 > NOTE: One could build a redux system on top of Qoot services.
 
-The key difference to standard subscription system based of function closures, the Qoot subscription system is based on DOM attribute. This allows the DOM to declare relationships between services and components without having to allocate and execute any subscription listeners or release any listeners when views go away. The subscription system in Qoot is fully declarative and has no runtime overhead of setting up the relationships.
+The critical difference to standard subscription system based on function closures, the Qoot subscription system is based on DOM attributes. This allows the DOM to declare relationships between services and components without allocating and executing any subscription listeners or releasing listeners when views go away. The subscription system in Qoot is fully declarative and has no runtime overhead of setting up the relationships.
 
-> In practice Qoot uses `querySelectorAll` to find all listeners which are interested in particular state change and only re-hydrates the listening component if the component needs to be re-rendered.
+> In practice, Qoot uses `querySelectorAll` to find all listeners interested in specific state changes and only re-hydrates the listening component if the component needs to be re-rendered.
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,19 @@
+# Qoot Documentation
+
+## Understanding Concepts
+
+- [Mental Model](./MENTAL_MODEL.md)
+- [Bootstrapping](./BOOTSTRAP.md)
+- [Resumable vs Replayable applications](./RESUMABLE.md)
+- Component's [host-element](./HOST_ELEMENT.md)
+- [Lazy Loading](./LAZY_LOADING.md)
+- [Qoot URL](./QRL.md)
+- [Qoot Reactivity](./REACTIVITY.md)
+
+## Getting Started
+
+- [Examples](../integration/README.md)
+
+## Cheat Sheet
+
+- [DOM attributes](./CHEAT_SHEET.md)
diff --git a/integration/README.md b/integration/README.md
@@ -6,14 +6,15 @@ This folder contains both e2e integration tests as well as examples of usage of
 
 - [`hello_static`](./hello_static/): The simplest possible app demonstrating lazy loading (but not server-side rendering.)
 - [`hello_server`](./hello_server/): A simple example with server-side rendering demonstrating re-hydration of the application on the client.
+- [`todo`](./todo/): Classical ToDo application implemented with Qoot.
 
 ## Running
 
 1. First, start the server
 
-```
-bazel run integration:server
-```
+   ```
+   bazel run integration:server
+   ```
 
 2. Open the browser http://localhost:8080
 3. Navigate to one of the examples.