Branches for docs workflows | NookDocs

Most engineering branching strategies (Gitflow, GitHub Flow, Trunk-Based) were designed for code that breaks the build if you merge it half-done. Docs rarely do that — a half-written page is still a page, just an incomplete one. That means docs teams can use a lighter branching model than code teams.

This guide covers the branching conventions that actually fit docs work.

The simplest model — direct to main

For most docs commits, there's no reason to branch. Typo fixes, broken-link fixes, adding a paragraph, updating a link — all go straight to main via the dashboard editor or a direct commit.

main ─┬─── small edit ─┬─── typo fix ─┬─── paragraph add ─┬─── (live)
      │               │              │                   │
      └── every commit deploys within 30-60s

Use direct-to-main when:

The change is under 20 minutes of work.
You're confident the change is correct.
No coordination with teammates needed.
The page isn't load-bearing for a launch or compliance moment.

This covers ~80% of docs commits for most teams.

When to branch

Branch when:

Multi-day rewrites

Rewriting a 1000-word concept page across three days. Users shouldn't see the half-done state. Branch + merge when complete.

Coordinated with a product launch

Docs for a feature shipping next Tuesday. Page must be live at the launch hour, not before. Work on a branch; merge at launch time.

Needs review before going live

Legal disclaimer wording. Security disclosure. Pricing page. Anything where wrong wording is worse than no wording. Branch + PR review.

Experimental restructuring

Testing a new IA: moving 20 pages into a different section. If it doesn't work, you want to throw it away cleanly. Branch makes abandoning easy.

Branch naming

Simple patterns that scale:

Prefix	Use for	Example
`docs/<topic>`	Most docs work	`docs/webhook-guide`, `docs/rewrite-concepts`
`feature/<name>`	Docs for a new product feature	`feature/team-invites-docs`
`fix/<issue>`	Fixing a specific bug or broken content	`fix/custom-domain-caa-record`
`launch/<name>`	Launch-coordinated content	`launch/q2-pricing-update`
`experiment/<topic>`	Throwaway experiments	`experiment/tutorial-split-test`

Keep names short (under 40 chars), hyphenated, descriptive. docs/webhooks beats updating-the-webhook-documentation-page-with-new-fields.

Who commits to what

A convention that scales past 5 people:

Writers branch for anything over 20 minutes. Commit directly for small fixes.
Engineers branch whenever they touch docs as part of a code change — the same PR that ships the feature ships its doc.
Contractors / external reviewers always branch. Gives the internal team a chance to review before going live.

For a 2-3 person team, these distinctions often collapse — everyone branches for medium changes, everyone ships small ones direct.

Merge strategies

GitHub offers three merge button options. Docs teams usually want:

Strategy	What it does	When to use
Squash and merge	Combines all your branch commits into one on `main`	Default for most docs PRs. Keeps `main` history clean.
Rebase and merge	Replays your commits onto `main` as-is	When your commits tell a useful story each on their own (rare for docs).
Create a merge commit	Explicit merge commit showing the branch joined	Large feature branches with extensive history worth preserving.

Recommended default: Squash and merge. For docs, the commit history matters less than for code; a clean main history is easier to read.

Reviewer patterns

Docs PRs are lighter to review than code PRs. Reviewer focus:

Does it match the house style?

Voice, tone, heading format, component usage. See style and tone.

Does it render cleanly?

Preview the branch in the dashboard (if supported) or pull down locally. MDX parse errors should be caught by CI but eyeball for visual issues.

Are claims accurate?

Does the feature actually work the way the page describes? For reference docs, verify against code. For tutorials, run the tutorial end-to-end.

Cross-links present?

Every new page should link to + from 3-5 related pages. See linking.

Nav updated?

New pages need to be added to nookdocs.config.json#navigation to appear in the sidebar.

Target review time: 10-20 minutes for a single-page change. If review is taking longer than that, the PR is too big — ask the author to split.

PR template for docs changes

GitHub supports .github/PULL_REQUEST_TEMPLATE.md. For docs repos:

## Summary

(What does this PR change?)

## Motivation

(Why? Related ticket or feature launch?)

## Checklist

- [ ] Page parses cleanly (no MDX errors)
- [ ] Added to `nookdocs.config.json#navigation` if new
- [ ] Cross-linked to + from 3-5 related pages
- [ ] Frontmatter has title + description + icon
- [ ] Follows house style (voice, headings, ParamField usage)
- [ ] If a screenshot changed: alt text updated
- [ ] If documenting a breaking change: changelog entry added

## Screenshots

(If visual changes — before/after)

Triggers the right review discipline without slowing anyone down.

Protection rules

For teams where docs quality matters enough to enforce mechanically, configure GitHub branch protection on main:

Require PR reviews

"Require approvals: 1" means every change needs a second pair of eyes. Overkill for small teams; mandatory for teams over ~10 people.

Require status checks

MDX parse check + check-sync + build must pass before merge. Catches errors the reviewer missed.

Require branches to be up-to-date

Prevents "my branch is 3 weeks behind main" merges. Forces pulling in latest changes first.

Restrict who can push to main

Prevents accidental force-pushes or direct commits that skip review. Keep a small admin list.

For 1-2 person teams: skip protection rules. Friction outweighs benefits.

Branch lifetime

Short branches reduce merge pain:

Hours-to-days — most docs branches.
Up to 1 week — bigger rewrites. Pull from main daily to stay current.
Over 1 week — probably scope bloat. Ship in pieces rather than batching.

Branches that live 3+ weeks accumulate enough drift from main that merging becomes a multi-conflict archaeology project. Prevention beats cure.

Draft PRs

GitHub's "Draft PR" feature lets you open a PR that explicitly ISN'T ready for review. Useful for:

Long in-progress work where you want CI to run continuously.
Soliciting early feedback on structure before investing in polish.
Coordinating with an engineer on a page + code change happening in parallel.

Open as draft, work, convert to "Ready for review" when done. Reviewers know not to spend review cycles on a draft.

Common branch-workflow mistakes

Git concepts — prerequisite primer
Configure automerge — automate the merge step for low-risk PRs
Maintenance — how branch discipline feeds into freshness audits
Style and tone — the reviewer's checklist