Git
When you’re documenting three features simultaneously, releasing a weekly service pack for bug fixes on main, and requesting reviews from SMEs and other tech writers, you need serious control over versioning. Git provides this and more. It’s an indispensable tool for keeping docs properly versioned and organized.
On this page, I’ll mention my favorite aspects of Git and list a few common uses. For an overview of how I use Git in my typical workflow, see Docs as code.
Commits
A wise developer once told me, "commit early and often." This is great advice because it leaves a clear breadcrumb trail of your work.
$ git commit -m "ID-123 updated pricing structure for international clients"
A descriptive commit message is helpful in case you need to revert a change or create a branch or tag at a specific commit.
| Try to keep commits smaller and well scoped. Changes are easier to manage when in related, bite-sized chunks. |
Another one of Git’s strengths is the redundancy it offers through the local/remote repository structure. Not only does this give you a local sandbox to commit your work, but it also creates constant remote back-ups with each git push. This is helpful, since you never know when the Blue screen of death may come.
Commit early and often to save your work in the remote repo!
Branching
Branching with Git lets you compartmentalize work in separate locations. This is helpful whether working alone on different features or alongside other tech writers. Of course, working on feature branches frees up your main branch for releases. Branches shouldn’t linger around for too long, either. I prefer a feature branch to not last more than a couple of months, ideally. I’ll periodically merge the latest from main branch into my feature branches to keep them up-to-date. This reduces the likelihood of merge conflicts later on.
Branching also makes automated releases of docs possible. Commits merged to main can kick off deployments to production, while commits merged to dev could deploy to a staging environment.
Reversion
Oops! Did you make that commit on the wrong branch? Or completely break the test site with no clue of what you did?
| None of this has ever happened to me, I promise… |
Git makes it easy to pretend those mistakes never happened.
Use git revert COMMIT-HASH to "soft" delete a commit using its hash ID. This method keeps the history in your git log and can be undone, if needed.
Use git reset --hard HASH to "hard" delete a commit and erase its history. This cannot be undone, so use carefully.
Tags and releases
Once you reach a milestone, Git tags and releases offer a convenient way to mark a commit for easy reference. Rather than paging through thousands of commit looking for last quarter’s release, make a tag or release showcasing the shipped docs. You can handle versions, branches, or revisions of already released content with ease using tags and releases.
git tag -a v1.0.1 -m "hotfix for SVE-1234" && git push origin v1.0.1