From 651e352f3a6bed5fcef2fd4ce51a3bb9c4ed8a2a Mon Sep 17 00:00:00 2001
From: Aaron Smith <83140718+centau@users.noreply.github.com>
Date: Mon, 14 Aug 2023 12:11:46 +0100
Subject: [PATCH] Improve docs

---
 docs/tut/crash-course/5-derived-source.md | 43 +++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/docs/tut/crash-course/5-derived-source.md b/docs/tut/crash-course/5-derived-source.md
index 90ab2b3..a8b5b05 100644
--- a/docs/tut/crash-course/5-derived-source.md
+++ b/docs/tut/crash-course/5-derived-source.md
@@ -57,3 +57,46 @@ create "TextLabel" {
 count(3) -- displays "factorial squared: 36"
 count(4) -- displays "factorial squared: 576"
 ```
+
+Vide knows what sources are being depended on by immediately running the
+callback when deriving or binding sources. If a source is in a function but is
+never referenced the first time it runs, Vide will not know to rerun the
+function if that source changes.
+
+An example to watch out for is when using sources within branches:
+
+```lua
+local condition = source(true)
+local count1 = source(0)
+local count2 = source(0)
+
+local text = function()
+    if condition() then
+        return "text: " .. count1()
+    else
+        return "text: " .. count2()
+    end
+end
+```
+
+In the above case, only `count1` will be referenced, meaning `text` will not be
+aware of `count2` even if the condition is later set to false.
+
+All sources to be tracked must be referenced the first time the function runs.
+
+```lua
+local condition = source(true)
+local count1 = source(0)
+local count2 = source(0)
+
+local text = function()
+    local c1 = count1()
+    local c2 = count2()
+
+    if condition() then
+        return "text: " .. c1
+    else
+        return "text: " .. c2
+    end
+end
+```