diff --git a/README.md b/README.md
index 66d6f661..b8ca3b99 100644
--- a/README.md
+++ b/README.md
@@ -458,8 +458,8 @@ Some things to note about the above code:
 #### Definition
 
 Workflows are defined as classes decorated with `@workflow.defn`. The method invoked for the workflow is decorated with
-`@workflow.run`. Methods for signals and queries are decorated with `@workflow.signal` and `@workflow.query`
-respectively. Here's an example of a workflow:
+`@workflow.run`. Methods for signals, queries, and updates are decorated with `@workflow.signal`, `@workflow.query`
+and `@workflow.update` respectively. Here's an example of a workflow:
 
 ```python
 import asyncio
@@ -515,6 +515,12 @@ class GreetingWorkflow:
     @workflow.query
     def current_greeting(self) -> str:
         return self._current_greeting
+    
+    @workflow.update
+    def set_and_get_greeting(self, greeting: str) -> str:
+      old = self._current_greeting
+      self._current_greeting = greeting
+      return old
 
 ```
 
@@ -582,6 +588,14 @@ Here are the decorators that can be applied:
   * All the same constraints as `@workflow.signal` but should return a value
   * Should not be `async`
   * Temporal queries should never mutate anything in the workflow or call any calls that would mutate the workflow
+* `@workflow.update` - Defines a method as an update
+  * May both accept as input and return a value
+  * May be `async` or non-`async`
+  * May mutate workflow state, and make calls to other workflow APIs like starting activities, etc.
+  * Also accepts the `name` and `dynamic` parameters like signals and queries, with the same semantics.
+  * Update handlers may optionally define a validator method by decorating it with `@update_handler_method.validator`.
+    Validators cannot be `async`, cannot mutate workflow state, and return nothing. They can be used to reject update 
+    calls before any events are written to history by throwing an exception.
 
 #### Running