copyedit git concepts

Author: ethanpalm

editor/git-concepts.mdx

@@ -1,102 +1,60 @@
 ---
 title: "Git concepts"
-description: "Learn how the web editor integrates with Git version control"
+description: "Learn Git fundamentals for the docs-as-code workflow"
 ---
 
-The web editor handles Git operations automatically, but understanding these concepts will help you work more effectively and collaborate better with team members using local development environments.
+Git is a version control system that allows you to track changes to your documentation and collaborate with team members. With Git, for every file in your project, you can see what changed, when, and why. Git also makes it easy to revert to previous versions of files if you ever need to.
+
+The web editor performs some Git operations behind the scenes. Understanding these concepts will help you work more effectively with the web editor and collaborate with team members who are working in their local development environments.
 
 ## Core Git concepts
 
 <AccordionGroup>
   <Accordion title="Repository">
-    Your documentation's source where all files and their history are stored. The web editor connects to your repository to access and modify content. Think of it as the master database for all your documentation files.
+    Your documentation's source where all files and their history are stored. The web editor connects to your repository to access and modify content.
   </Accordion>
 
   <Accordion title="Commit">
     A saved snapshot of your changes at a specific point in time. Each commit includes a message describing what changed and creates a permanent record in your project history.
   </Accordion>
 
   <Accordion title="Branch">
-    A separate workspace for making changes without affecting your live documentation. Think of it as a safe sandbox for experiments and larger updates where you can work on features independently.
+    A branch points to a specific commit in your repository. Your live documentation is built from a deployment branch. You can have any number of other branches with changes that are not yet published to your live documentation. If you want to incorporate the changes from a branch into your live documentation, you can merge the branch into your deployment branch through a pull request.
+    
+    Use branches to work on changes without affecting your live documentation, safely experiment with new features, and get reviews before publishing. 
   </Accordion>
 
   <Accordion title="Deployment branch">
-    The main branch that contains your live documentation content. Changes to this branch are automatically published to your documentation site. Often called `main` or `master`.
+    The primary branch of your project that your live documentation content is built from. Changes to this branch are automatically published to your documentation site. Often called `main`, but you can set any branch as your deployment branch.
   </Accordion>
 
   <Accordion title="Pull request">
-    A way to propose merging your branch changes into your live documentation. Allows for review and discussion before changes go live. Also called a merge request in GitLab.
+    A way to propose merging your changes on a branch into your live documentation. Allows for review and discussion before changes go live. Commonly called a PR, and also called a merge request in GitLab.
   </Accordion>
 
   <Accordion title="Diff">
-    Shows the specific changes between two versions of a file. When reviewing pull requests, diffs highlight what has been added, removed, or modified, making it easy to see exactly what changed.
+    A diff (or difference) shows the changes between two versions of a file. When reviewing pull requests, diffs highlight what has been added, removed, or modified, making it easy to identify what changed.
 </Accordion>
 </AccordionGroup>
 
 ## How the web editor uses Git
 
-The web editor connects to your Git repository through the [GitHub App](/settings/github) or [GitLab integration](/settings/gitlab) and automates common Git operations:
-
-### Automatic operations
-
-**When you open a file**: The editor fetches the latest version from your repository, ensuring you're always working with current content.
-
-**When you make changes**: The editor tracks your modifications as a draft that can become a commit when you're ready to save.
-
-**When you save changes**: Creates a commit with your changes and a descriptive message, preserving your work in the project history.
-
-**When you create a branch**: Sets up a new branch in your repository for isolated development work.
-
-**When you publish**: Either commits directly to your deployment branch (immediate publishing) or creates a pull request (review workflow).
-
-### Behind the scenes
-
-The web editor abstracts away complex Git commands while maintaining all the benefits of version control:
-
-- **Version history**: Every change is tracked with timestamps and descriptions
-- **Collaboration**: Multiple people can work simultaneously without conflicts
-- **Rollback capability**: Previous versions are always recoverable
-- **Branch isolation**: Experimental changes don't affect live content
-
-## Why Git matters for documentation
-
-### Version control benefits
-- **Track changes**: See exactly what changed, when, and why
-- **Collaborate safely**: Multiple team members can contribute without overwriting each other's work  
-- **Rollback protection**: Easily revert to previous versions if something goes wrong
-- **Audit trail**: Complete history of who made what changes
-
-### Collaborative workflows
-- **Review process**: Pull requests enable team members to review changes before they go live
-- **Parallel development**: Different team members can work on different features simultaneously
-- **Integration**: Works seamlessly with developer workflows and CI/CD pipelines
-
-## Git vs. traditional documentation tools
-
-Unlike traditional documentation platforms, Git-based workflows provide:
-
-- **Developer integration**: Your docs live alongside your code in familiar developer tools
-- **Branching**: Safe experimentation without affecting live content
-- **Merge conflicts**: Intelligent handling when multiple people edit the same content
-- **External collaboration**: Contributors can propose changes even without direct access
+The web editor connects to your Git repository through the [GitHub App](/settings/github) or [GitLab integration](/settings/gitlab) and automates common Git operations.
 
-## Best practices
+When you:
 
-### Commit messages
-The web editor generates descriptive commit messages automatically, but understanding good commit practices helps when reviewing history:
+- **Open a file**: The editor fetches the latest version from your repository, ensuring you're always working with up to date content.
+- **Make changes**: The editor tracks your changes as a draft that can become a commit when you're ready to save your work.
+- **Save changes**: The editor makes a commit with your changes, preserving your work in the project history.
+- **Create a branch**: The editor creates a new branch in your repository that can be used by anyone with access to the repository so they can collaborate and review changes.
+- **Publish on your deployment branch**: The editor commits and pushes directly to your deployment branch, which publishes your changes immediately.
+- **Publish on other branches**: The editor creates a pull request, which allows you to get feedback from others before merging your changes into your deployment branch.
 
-- Be specific about what changed
-- Explain why the change was made
-- Keep messages concise but informative
+## Git best practices
 
-### Branching strategy
-- Use feature branches for new content or major updates
-- Keep branches focused on specific tasks or features
-- Merge regularly to avoid large, complex merges
-- Delete branches after merging to keep the repository clean
+Every team will develop their own workflows and preferences, but these are some general best practices to get you started.
 
-### Collaboration
-- Communicate with team members about active branches
-- Review pull requests thoroughly before merging
-- Pull latest changes before starting new work
-- Use descriptive branch names that explain the work being done
+- **Write descriptive commit messages**: Be specific about what changed using active language.
+- **Use descriptive branch names**: Branch names should explain the work being done and be meaningful to someone who is looking at the branches in your repository.
+- **Keep branches focused**: Keep the changes on a branch focused on a specific task or project.
+- **Delete branches after merging**: Delete branches when you no longer need them to keep your repository tidy.