Update docs

docs/api/animation.md

@@ -18,8 +18,8 @@ Returns a new source with a value always moving torwards the input source value.
 
 - **Details**
 
-    The output source value is updated every step based on the input source
-    value.
+    An effect is created to update the new source every frame based on the input
+    source value.
 
     The movement is physically simulated according to a
     [spring](https://en.wikipedia.org/wiki/Simple_harmonic_motion).

docs/api/creation.md

@@ -18,10 +18,10 @@ target instance.
     The result of the function is applied to a target in the same way
     properties are using `create()`.
 
-    The function is ran in a new reactive scope, just like
+    The function is ran in a new stable scope, just like
     [root()](reactivity-core.md#root).
 
-    Returns a function that when called will destroy the reactive scope.
+    Returns a function that when called will destroy the stable scope.
 
 - **Example**
 
@@ -170,7 +170,7 @@ A wrapper for `action()` to listen for property changes.
     Will run the given callback any time the property is changed, as well as
     when the action is initially run.
 
-    The changed connection is disconnected when the reactive scope the action is
-    ran in is destroyed.
+    The changed connection is disconnected when the scope the action is ran in
+    is destroyed.
 
     Runs with an action priority of 1.

docs/api/reactivity-core.md

@@ -42,11 +42,6 @@ Creates a new source with the given value.
     Calling the returned source with no argument will return its stored value,
     calling with an argument will set a new value.
 
-    Reading from the source from within a reactive scope will cause changes
-    to that source to be tracked and anything depending on it to update.
-
-    Sources can be created outside of reactive scopes.
-
 - **Example**
 
     ```lua
@@ -69,10 +64,10 @@ Runs a side-effect in a new reactive scope on source update.
 
 - **Details**
 
-    Any time a source referenced in the callback is changed, the callback will
+    Any time a source referenced in the callback is updated, the callback will
     be reran.
 
-    The callback is ran to initially ran on first call to find dependent sources.
+    The callback is ran once immediately.
 
 - **Example**
 
@@ -108,7 +103,7 @@ Derives a new source in a new reactive scope from existing sources.
     Anytime its value is recalculated it is also cached, subsequent calls will
     retun this cached value until it recalculates again.
 
-    The callback is ran to initially ran on first call to find dependent sources.
+    The callback is ran once immediately.
 
 - **Example**
 

docs/api/reactivity-flow.md

@@ -18,12 +18,12 @@ Shows one of two components depending on an input source.
     Returns a source holding an instance of the currently shown component.
 
     When the input source changes from a falsey to a truthy value, the
-    component will be reran under a new reactive scope. If it changes from a
-    truthy to falsey value, the reactive scope the component was created in will
+    component will be reran under a new stable scope. If it changes from a
+    truthy to falsey value, the stable scope the component was created in will
     be destroyed, and the returned source will output `nil`, or a fallback
     component if given.
 
-    The fallback component is also ran under a new reactive scope, and destroyed
+    The fallback component is also ran under a new stable scope, and destroyed
     when the input source switches back to truthy.
 
 ## switch()
@@ -41,10 +41,10 @@ Shows one of a set of components depending on an input source and a mapping tabl
     Returns a source holding an instance of the currently shown component.
 
     When the input source changes, the new value will be used to lookup a given
-    mapping table to get a component, which will be ran under a new reactive
-    scope. If the input source changes, the reactive scope the component was
+    mapping table to get a component, which will be ran under a new stable
+    scope. If the input source changes, the stable scope the component was
     created in will be destroyed, and a new component created under a new
-    reactive scope. If no component is found for an input value, the switch will
+    stable scope. If no component is found for an input value, the switch will
     output `nil`.
 
 - **Example**
@@ -82,9 +82,9 @@ Maps each index in a table source to an object.
     When the input source changes, each *index* in the new table is compared with
     the last input table.
 
-    - For any new index, the `transform` function is ran under a new reactive
+    - For any new index, the `transform` function is ran under a new stable
       scope to produce a new instance.
-    - For any removed index, the reactive scope for that index is destroyed.
+    - For any removed index, the stable scope for that index is destroyed.
     - Unchanged indexes are untouched.
 
     The transform function is called only ever *once* for each index in the
@@ -142,9 +142,9 @@ Maps each value in a table source to an object.
     When the input source changes, each *value* in the new table is compared with
     the last input table. Similar to `indexes()` but for values instead of indexes.
 
-    - For any new value, the `transform` function is ran under a new reactive
+    - For any new value, the `transform` function is ran under a new stable
       scope to produce a new instance.
-    - For any removed value, the reactive scope for that value is destroyed.
+    - For any removed value, the stable scope for that value is destroyed.
     - Unchanged values are untouched.
 
     The transform function is only ever called *once* for each value in the
@@ -203,7 +203,7 @@ Maps each value in a table source to an object.
     - Toast notifications.
 
     `indexes()` should be used in other cases, especially when your source table
-    has primitive value. It maps an index to a UI element.
+    has primitive values. It maps an index to a UI element.
 
     e.g.
     - List of character or weapon stats.
@@ -213,6 +213,6 @@ Maps each value in a table source to an object.
     result in less property updates and less re-renders. One case to note is
     that `values()` works nicely when animating re-ordering of instances, since
     the value is not destroyed when indexes are changed, and the source index
-    can easily be put through a spring.
+    can be used to animate a change in position for the UI element.
 
 --------------------------------------------------------------------------------

docs/api/reactivity-utility.md

@@ -2,7 +2,7 @@
 
 ## cleanup()
 
-Runs a callback anytime a reactive scope is reran or destroyed.
+Runs a callback anytime a scope is reran or destroyed.
 
 - **Type**
 
@@ -31,8 +31,7 @@ Runs a callback anytime a reactive scope is reran or destroyed.
 
 ## untrack()
 
-Runs a given function where any sources read will not be tracked by a reactive
-scope.
+Runs a given function in a new stable scope.
 
 - **Type**
 
@@ -42,8 +41,8 @@ scope.
 
 - **Details**
 
-    Updates made to a source passed to `untrack()` will not cause updates to
-    anything depending on that source.
+    Can be used inside a reactive scope to read from sources you do not want
+    tracked by the reactive scope.
 
 - **Example**
 
@@ -76,7 +75,7 @@ read can still be tracked inside a reactive scope.
 ## batch()
 
 Runs a given function where any source updates made within the function do not
-trigger effects until after the function runs.
+trigger effects until after the function finishes running.
 
 - **Type**
 

docs/api/strict-mode.md

@@ -22,12 +22,12 @@ Currently, strict mode will:
 6. Checks for duplicate nested properties at same depth.
 7. Better error reporting and stack traces + creation traces of property bindings.
 
-By rerunning derived sources and effects twice each time they update,it helps
+By rerunning derived sources and effects twice each time they update, it helps
 ensure that derived source computations are pure, and that any
 cleanups made in derived sources or effects are done correctly.
 
 Accidental yielding within reactive scopes can break Vide's reactive graph,
-which strict mode can catch.
+which strict mode will catch.
 
 As well as additional safety checks, Vide will dedicate extra resources to
 recording and better emitting stack traces where errors occur, particularly

docs/tut/crash-course/12-actions.md

@@ -24,6 +24,7 @@ action used to listen for property changes:
 
 ```lua
 local action = vide.action
+local effect = vide.effect
 local cleanup = vide.cleanup
 
 local function changed(prop: string, callback: (new) -> ())
@@ -44,9 +45,11 @@ local instance = create "TextBox" {
     changed("Text", output)
 }
 
-instance.Text = "foo"
+effect(function()
+    print(output())
+end)
 
-print(output()) -- "foo"
+instance.Text = "foo" -- "foo" will be printed from the effect
 ```
 
 The source `output` will be updated with the new property value any time it is

docs/tut/crash-course/2-creation.md

@@ -3,7 +3,7 @@
 Instances are created using `create()`.
 
 Parentheses `()` can be omitted when calling functions with string or
-table literals which is recommended for brevity.
+table literals for brevity.
 
 ```lua
 local create = vide.create