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
+    An effect is created to update the new source every frame based on the input
-    value.
+    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
+    The changed connection is disconnected when the scope the action is ran in
-    ran in is destroyed.
+    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
+    component will be reran under a new stable scope. If it changes from a
-    truthy to falsey value, the reactive scope the component was created in will
+    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
+    mapping table to get a component, which will be ran under a new stable
-    scope. If the input source changes, the reactive scope the component was
+    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
+Runs a given function in a new stable scope.
-scope.
 
 - **Type**
 
@@ -42,8 +41,8 @@ scope.
 
 - **Details**
 
-    Updates made to a source passed to `untrack()` will not cause updates to
+    Can be used inside a reactive scope to read from sources you do not want
-    anything depending on that source.
+    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

@@ -27,7 +27,7 @@ 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