Git — Docs That Change With the Code
Nightjar keeps its documentation in the same Git repository as its code, in a docs/ folder of Markdown files. So when you fix the quick start's missing login step, you do not email a file around. You propose a change that an engineer can review line by line, and when it is accepted, the docs site rebuilds by itself. This way of working is often called docs as code.
The rule
Every doc change gets its own branch, a clear commit and a reviewed merge.
The words you need:
- Repository: the project's folder together with its complete history.
- Commit: a saved snapshot of your changes, with a message saying what changed and why.
- Branch: a separate line of work, so your draft does not disturb the published docs.
- Pull request (some platforms call it a merge request): a proposal to bring your branch into the main one, where reviewers see exactly which lines changed and comment on them.
- Merge: accepting the change into the main branch. For a docs site, that usually means it publishes automatically.
- History: every change, who made it and when. When a reader asks "when did the default interval change?", the history answers.
The everyday commands for the login fix:
git switch -c docs/quick-start-login
# edit docs/quick-start.md, then:
git add docs/quick-start.md
git commit -m "Add missing login step to quick start"
git push -u origin docs/quick-start-logingit switch -c creates a branch and moves onto it; older Git versions use git checkout -b for the same job. After the push, you open the pull request on the hosting platform, such as GitHub or GitLab.
The shortcut
One change, one branch, one message that says why. Small, focused changes get reviewed quickly and can be undone cleanly.
Branch
Name the branch after the change:
docs/quick-start-login.
The trap is the giant pull request: a typo fix, a restructure and two new pages bundled together. Reviewers put it off, one disputed part blocks the rest, and undoing a single piece becomes painful.
Drills
Answer fast — trust the rule.
What is a branch for?
Which commit message is most useful?
Where do reviewers comment on specific lines of your doc change?
You have a typo fix and a full restructure of the alerts section. How should you submit them?
Why keep docs in the same repository as the code?
Remember
- Every doc change gets its own branch, a clear commit and a reviewed merge.
- Shortcut: one change, one branch, one message that says why.
- Trap: the giant pull request that bundles unrelated changes.