From c337228f4fc24294178a02fca4cee8f6e280ea39 Mon Sep 17 00:00:00 2001
From: Rick Hanlon <rickhanlonii@gmail.com>
Date: Sun, 20 Mar 2022 18:12:43 -0400
Subject: [PATCH 1/2] [18] Add start/useTransition docs

---
 content/docs/hooks-reference.md | 38 ++++++++++++++++++++++++++++++++-
 content/docs/reference-react.md | 11 ++++++----
 2 files changed, 44 insertions(+), 5 deletions(-)

diff --git a/content/docs/hooks-reference.md b/content/docs/hooks-reference.md
index 8ba19280fd1..1a4509262c5 100644
--- a/content/docs/hooks-reference.md
+++ b/content/docs/hooks-reference.md
@@ -565,7 +565,43 @@ Memoizing the children tells React that it only needs to re-render them when `de
 const [isPending, startTransition] = useTransition();
 ```
 
-TODO: description
+Returns a stateful value for the pending state of the transition, and a function to start it.
+
+`startTransition` lets you mark updates in the provided callback as transitions:
+
+```js
+startTransition(() => {
+  setCount(count + 1);
+})
+```
+
+`isPending` indicates when a transition is active to show a pending state:
+
+```js
+function App() {
+  const [isPending, startTransition] = useTransition();
+  const [count, setCount] = useState(0);
+  
+  function handleClick() {
+    startTransition(() => {
+      setCount(c => c + 1);
+    })
+  }
+
+  return (
+    <div>
+      {isPending && <Spinner />}
+      <button onClick={handleClick}>{count}</button>
+    </div>
+  );
+}
+```
+
+> Note:
+>
+> Updates in a transition yield to more urgent updates such as clicks.
+>
+> Updates in a transitions will not show a fallback for re-suspended content, allowing the user to continue interacting while rendering the update.
 
 ### `useId` {#useid}
 
diff --git a/content/docs/reference-react.md b/content/docs/reference-react.md
index db1eea55d55..2fa526284f4 100644
--- a/content/docs/reference-react.md
+++ b/content/docs/reference-react.md
@@ -383,9 +383,12 @@ a higher priority than neighboring boundaries. [Read more](https://github.com/re
 ```js
 React.startTransition(callback)
 ```
-
-TODO: description
+`React.startTransition` lets you mark updates inside the provided callback as transitions. This method is designed to be used outside a hook context when [`React.useTransition`](/docs/hooks-reference.html#usetransition) is not available.
 
 > Note:
-> 
-> TODO: useTransition
+>
+> Updates in a transition yield to more urgent updates such as clicks.
+>
+> Updates in a transitions will not show a fallback for re-suspended content, allowing the user to continue interacting while rendering the update.
+>
+> `React.startTransition` does not provide an `isPending` flag. To track the pending status of a transition see [`React.useTransition`](/docs/hooks-reference.html#usetransition).

From efc1ebfc82cd76971a9e3cab5ec39a99a9d8a8a1 Mon Sep 17 00:00:00 2001
From: Rick Hanlon <rickhanlonii@gmail.com>
Date: Sun, 27 Mar 2022 13:33:24 -0400
Subject: [PATCH 2/2] Updates based on feedback

---
 content/docs/hooks-reference.md | 2 +-
 content/docs/reference-react.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/content/docs/hooks-reference.md b/content/docs/hooks-reference.md
index 1a4509262c5..c5a676ab12f 100644
--- a/content/docs/hooks-reference.md
+++ b/content/docs/hooks-reference.md
@@ -601,7 +601,7 @@ function App() {
 >
 > Updates in a transition yield to more urgent updates such as clicks.
 >
-> Updates in a transitions will not show a fallback for re-suspended content, allowing the user to continue interacting while rendering the update.
+> Updates in a transitions will not show a fallback for re-suspended content. This allows the user to continue interacting with the current content while rendering the update.
 
 ### `useId` {#useid}
 
diff --git a/content/docs/reference-react.md b/content/docs/reference-react.md
index 2fa526284f4..6284bb8ff67 100644
--- a/content/docs/reference-react.md
+++ b/content/docs/reference-react.md
@@ -383,7 +383,7 @@ a higher priority than neighboring boundaries. [Read more](https://github.com/re
 ```js
 React.startTransition(callback)
 ```
-`React.startTransition` lets you mark updates inside the provided callback as transitions. This method is designed to be used outside a hook context when [`React.useTransition`](/docs/hooks-reference.html#usetransition) is not available.
+`React.startTransition` lets you mark updates inside the provided callback as transitions. This method is designed to be used when [`React.useTransition`](/docs/hooks-reference.html#usetransition) is not available.
 
 > Note:
 >