update conceptual info about branches

Author: ethanpalm

editor/branches.mdx

@@ -1,88 +1,56 @@
 ---
 title: "Working with branches"
-description: "Use branches to safely make changes without affecting your live documentation"
+description: "Use branches to make and review changes without affecting your live documentation"
 ---
 
-Branches let you work on changes without affecting your live documentation site. When your changes are ready, you can merge them into your deployment branch through a pull request.
+Branches are a version control feature that let you create separate instances of your documentation, then merge into your main branch if you want to publish your changes. Think of a branch as a copy of your documentation where you can experiment, make edits, and test changes before they go live.
 
-## Why use branches
+A benefit of branches is that your team can work simultaneously on seprate branches without getting in each other's way. Even if two different branches make changes to the same file, you will be required to resolve any conflicts before merging branches and publishing your docs updates.
 
-**Best practice: Always work from branches.** This approach:
+If you decide that you don't want to publish changes from a branch, you can delete the branch with no consequences. This makes branch a safe place to experiment and try new approaches to your content.
 
-- Keeps your live documentation stable while you make changes
-- Enables proper review workflows with your team
-- Creates a clear history of what changed and when
-- Allows you to experiment safely with new content or structure
-
-Even if you're working solo, branches are valuable for previewing changes before they go live.
+We recommend that you always work from branches when you're updating your documentation. This ensures that your live site stays stable and enables review workflows for any updates.
 
 ## Creating a branch
 
 <Steps>
   <Step title="Open the branch selector">
-    Select the branch name in the editor toolbar (usually `main` by default).
+    Select the branch name in the editor toolbar (usually `main`).
   </Step>
   <Step title="Create new branch">
     Select **New Branch** from the dropdown menu.
   </Step>
   <Step title="Name your branch">
-    Enter a descriptive name like:
+    Use a descriptive name that explains what you're working on:
     - `update-getting-started`
-    - `fix-installation-steps`  
-    - `add-api-examples`
+    - `fix-api-examples`  
+    - `restructure-navigation`
   </Step>
   <Step title="Create and switch">
-    Select **Create Branch**. The editor will switch to your new branch automatically.
+    Select **Create Branch**. The editor switches to your new branch automatically.
   </Step>
 </Steps>
 
 <Note>
-  If the editor doesn't automatically switch to your new branch, select it manually from the branch dropdown.
+  If the editor doesn't switch automatically, select your new branch from the dropdown menu.
 </Note>
 
-## Saving changes on a branch
-
-When you're working on a branch:
-
-1. Make your edits in visual mode or Markdown mode
-2. Select the **Save Changes** button in the top-right corner
-3. This creates a commit with your changes and pushes it to your branch
+## Saving and switching
 
-Your changes are now saved but not yet live on your documentation site.
+Save changes to your branch by selecting **Save Changes** in the top-right corner. This creates a commit and pushes your work to the branch.
 
-## Switching between branches
-
-<Steps>
-  <Step title="Open branch selector">
-    Select the current branch name in the editor toolbar.
-  </Step>
-  <Step title="Choose target branch">
-    Select the branch you want to switch to from the dropdown menu.
-  </Step>
-</Steps>
+To switch branches, select the current branch name in the toolbar and choose a different branch from the dropdown.
 
 <Tip>
-  Any unsaved changes will be lost when switching branches. Make sure to save your work first by selecting **Save Changes**.
+  Unsaved changes are lost when switching branches. Save your work first.
 </Tip>
 
-## Branch types
-
-### Deployment branch
-Your main branch (often called `main`) contains your live documentation content. Changes to this branch are automatically published to your documentation site immediately.
+## Understanding branch types
 
-### Feature branches
-Any branch other than your deployment branch. Use these for:
-- New feature documentation
-- Content updates and revisions  
-- Experimental changes
-- Collaborative work that needs review
+**Deployment branch**: Your main branch (usually `main`) contains your live documentation. Changes here publish immediately to your site.
 
-Changes on feature branches require a pull request to merge into your deployment branch.
+**Feature branches**: All other branches where you work on changes before they're ready to go live. These require a pull request to merge into your main branch.
 
-## Best practices
+## Working with your team
 
-- **Use descriptive branch names** that explain what you're working on
-- **Keep branches focused** on a single task or feature
-- **Save frequently** to avoid losing work when switching branches
-- **Delete branches** after merging to keep your repository clean
-- **Communicate with your team** about which branches are active
+Name branches clearly so teammates understand what you're working on. Delete branches after merging to keep your repository organized. Let your team know when you're working on major changes that might affect their work.