diff --git a/docs/namespaces.md b/docs/namespaces.md
index 122279e25..229450da5 100644
--- a/docs/namespaces.md
+++ b/docs/namespaces.md
@@ -161,3 +161,18 @@ sub Vertibrates_Reptiles_Hiss()
 end sub
 ```
 </details>
+
+
+## Caveats
+### ObserveField and ObserveFieldScoped
+It's incredibly difficult for brighterscript to know when it's safe to transpile strings that happen to look like namespace names. As such, the `ObserveField` and `ObserveFieldScoped` functions in BrighterScript do not automatically transpile string-based function names into their BrightScript-compatible underscore format.
+
+This means that if you pass a namespaced identifier as a string (i.e `Vertibrates.Birds.Quack`) it will not be converted to `Vertibrates_Birds_Quack` during transpilation. Developers need to ensure they manually provide the transpiled function name when using these functions to avoid runtime errors (i.e. `Vertibrates_Birds_Quack`).
+
+```brighterscript
+'this does not work
+m.top.observeField("someField", "Vertibrates.Birds.Quack")
+
+'you need to do this instead
+m.top.observeField("someField", "Vertibrates_Birds_Quack")
+```