docs: clarify read/update language in intro & readme

README.md

@@ -150,13 +150,28 @@ workflow to prevent cascading/waterfalling of updates. You can retrieve the curr
 
 Editor States are also fully serializable to JSON and can easily be serialized back into the editor using `editor.parseEditorState()`.
 
-### Editor Updates
+### Reading and Updating Editor State
 
-When you want to change something in an Editor State, you must do it via an update, `editor.update(() => {...})`. The closure passed
-to the update call is important. It's a place where you have full "lexical" context of the active editor state, and it exposes
-access to the underlying Editor State's node tree. We promote using `$` prefixed functions in this context, as it signifies a place
-where they can be used exclusively. Attempting to use them outside of an update will trigger a runtime error with an appropriate error.
-For those familiar with React Hooks, you can think of these as having a similar functionality (except `$` functions can be used in any order).
+When you want to read and/or update the Lexical node tree, you must do it via `editor.update(() => {...})`. You may also do
+read-only operations with the editor state via `editor.getEditorState().read(() => {...})`. The closure passed to the update or read
+call is important, and must be synchronous. It's the only place where you have full "lexical" context of the active editor state,
+and providing you with access to the Editor State's node tree. We promote using the convention of using `$` prefixed functions
+(such as `$getRoot()`) to convey that these functions must be called in this context. Attempting to use them outside of a read
+or update will trigger a runtime error.
+
+For those familiar with React Hooks, you can think of these $functions as having similar functionality:
+| *Feature* | React Hooks | Lexical $functions |
+| -- | -- | -- |
+| Naming Convention | `useFunction` | `$function` |
+| Context Required | Can only be called while rendering | Can only be called while in an update or read |
+| Can be composed | Hooks can call other hooks | $functions can call other $functions |
+| Must be synchronous | ✅ | ✅ |
+| Other rules | ❌ Must be called unconditionally in the same order | ✅ None |
+
+Node Transforms and Command Listeners are called with an implicit `editor.update(() => {...})` context.
+
+It is permitted to do nest updates within reads and updates, but an update may not be nested in a read.
+For example, `editor.update(() => editor.update(() => {...}))` is allowed.
 
 ### DOM Reconciler
 
@@ -253,11 +268,11 @@ used as the starting point. From a technical perspective, this means that Lexica
 called double-buffering during updates. There's an editor state to represent what is current on
 the screen, and another work-in-progress editor state that represents future changes.
 
-Creating an update is typically an async process that allows Lexical to batch multiple updates together in
-a single update – improving performance. When Lexical is ready to commit the update to
-the DOM, the underlying mutations and changes in the update will form a new immutable
-editor state. Calling `editor.getEditorState()` will then return the latest editor state
-based on the changes from the update.
+Reconciling an update is typically an async process that allows Lexical to batch multiple synchronous
+updates of the editor state together in a single update to the DOM – improving performance. When
+Lexical is ready to commit the update to the DOM, the underlying mutations and changes in the update
+batch will form a new immutable editor state. Calling `editor.getEditorState()` will then return the
+latest editor state based on the changes from the update.
 
 Here's an example of how you can update an editor instance:
 

packages/lexical-website/docs/intro.md

@@ -59,13 +59,28 @@ workflow to prevent cascading/water-falling of updates. You can retrieve the cur
 
 Editor States are also fully serializable to JSON and can easily be serialized back into the editor using `editor.parseEditorState()`.
 
-### Editor Updates
-
-When you want to change something in an Editor State, you must do it via an update, `editor.update(() => {...})`. The closure passed
-to the update call is important. It's a place where you have full "lexical" context of the active editor state, and it exposes
-access to the underlying Editor State's node tree. We promote using `$` prefixed functions in this context, as it signifies a place
-where they can be used exclusively. Attempting to use them outside of an update will trigger a runtime error with an appropriate error.
-For those familiar with React Hooks, you can think of these as having a similar functionality (except `$` functions can be used in any order).
+### Reading and Updating Editor State
+
+When you want to read and/or update the Lexical node tree, you must do it via `editor.update(() => {...})`. You may also do
+read-only operations with the editor state via `editor.getEditorState().read(() => {...})`. The closure passed to the update or read
+call is important, and must be synchronous. It's the only place where you have full "lexical" context of the active editor state,
+and providing you with access to the Editor State's node tree. We promote using the convention of using `$` prefixed functions
+(such as `$getRoot()`) to convey that these functions must be called in this context. Attempting to use them outside of a read
+or update will trigger a runtime error.
+
+For those familiar with React Hooks, you can think of these $functions as having similar functionality:
+| *Feature* | React Hooks | Lexical $functions |
+| -- | -- | -- |
+| Naming Convention | `useFunction` | `$function` |
+| Context Required | Can only be called while rendering | Can only be called while in an update or read |
+| Can be composed | Hooks can call other hooks | $functions can call other $functions |
+| Must be synchronous | ✅ | ✅ |
+| Other rules | ❌ Must be called unconditionally in the same order | ✅ None |
+
+Node Transforms and Command Listeners are called with an implicit `editor.update(() => {...})` context.
+
+It is permitted to do nest updates within reads and updates, but an update may not be nested in a read.
+For example, `editor.update(() => editor.update(() => {...}))` is allowed.
 
 ### DOM Reconciler