Skip to main content
Documentation rarely belongs to one person. Writers, engineers, product managers, and designers all make changes — often to the same sections, sometimes at the same time. Git is designed for exactly this, but a few habits make collaborative documentation work go much more smoothly.

​
The pull request review workflow

Pull requests are where collaboration happens. When you open a PR, your teammates can review the changes before they go live, and the conversation that happens in a PR is often as valuable as the changes themselves. A few things that make PR reviews work well: Keep PRs small and focused. A PR that changes one section of one page is easy to review. A PR that reorganizes the entire docs site touches hundreds of files and is nearly impossible to review meaningfully. If you’re doing large restructuring work, break it into a sequence of smaller PRs where possible. Write a useful PR description. Explain what changed and why — not just what files were modified. Reviewers shouldn’t have to reconstruct your reasoning from a diff. A single paragraph is usually enough. Request reviews from the right people. For technical accuracy, ask the engineer who owns the feature. For tone and structure, ask a writer. For strategic decisions about organization or what to document, ask a product manager. The right reviewer depends on what kind of feedback you need.

​
Working alongside engineers

The most effective documentation teams treat docs changes the same way engineering teams treat code changes: documentation for a new feature ships in the same pull request as the feature itself. This is easier said than done, but worth working toward. When an engineer opens a PR to ship a new feature, they can add a docs update to the same PR — or open a linked PR in the docs repository. The benefit is that docs are reviewed and published at the same time as the feature, rather than days or weeks later when the details have faded. If your engineering team merges code without updating docs, Mintlify’s agent can help close the gap by drafting documentation updates automatically when code is merged. It’s not a substitute for engineers thinking about documentation as part of shipping, but it’s a useful safety net.

​
Merge conflicts

A merge conflict happens when two people change the same part of the same file in different branches, and Git can’t automatically figure out how to combine them. Conflicts look scarier than they are. Git marks the conflicting section in the file like this: 
<<<<<<< your-branch
This is the text you wrote.
=======
This is the text someone else wrote.
>>>>>>> main
Resolving it means deciding what the final version should say — keeping one version, the other, or combining them — and deleting the conflict markers. Most code editors and GitHub’s web interface have built-in tools that make this easier than working with the raw markers. The best way to deal with conflicts is to make them unlikely:
  • Keep branches short-lived. The longer a branch exists, the more main moves on without it. Open PRs quickly and merge them quickly.
  • Pull from main frequently. If you’re working on a branch for more than a day, bring in the latest changes from main regularly with git pull origin main.
  • Coordinate on shared sections. If you and a colleague are both working on the same part of the docs, a quick conversation upfront saves a conflict resolution later.

​
Branch protection

Your Mintlify documentation repository likely has branch protection rules on main — settings that prevent changes from being pushed directly to the live branch without going through a pull request. This is intentional. Direct pushes to main bypass the review step entirely, which means changes go live without a preview or a chance for anyone else to catch problems. Branch protection is a guardrail worth keeping in place even when it feels like friction. If you need to make an urgent fix, the fastest path is still a PR. The review can be quick, and the preview deployment gives you confidence that the fix does what you intend. That’s the end of the Git and GitHub for Mintlify course. You now have the full picture: how Git tracks changes, how GitHub adds collaboration and review, and how Mintlify builds on both to give your team a reliable docs workflow. When you’re ready to put it to work, the Structure docs that scale course covers how to design docs that stay useful as your product grows.