Git workflow for technical writing

You’ve set up Git, your GitHub repo, and your editor … what’s next? Before you start writing in Markdown, it’s worth learning the Git workflow and some key terms.

But first, a big shout out to Deborah Barnard, Aleksei Stepanov, and Andrew Owen who have really helped me get a grip on how projects are usually set up and git workflows for documentation.

Some Git jargon to get us started

Unfortunately, there’s some jargon involved with Git and you have to learn it. Or if not learn it, at least become familiar enough that you can search for what it means and you’ll be able to understand the answer!

Let’s look at a few of the terms that you’ll need to understand to start working.

• Repo
  Short for repository. A repo is where Git stores your project’s content and its history. You’ll work locally in the repo on your computer. When your work’s ready for review, you’ll push it to the remote repo (GitHub) so your colleagues can see it.

• Pull
  This means to download the latest content from the remote repo to your local repo. You should do this at the start of your work, before you create a branch (see below), and also periodically.

• Branch
  A branch is a version of the content.
  
  For example, you might have a branch for publishing the current version of the content and another branch for a work-in-progress update for a future release.

• Staging
  This is the process of telling Git which of the changes you’ve made in your local repo should be included in the next commit (save + version history). You can stage some files and not others, so you can group changes into meaningful chunks.

• Commit
  Think of a commit as a way of saving your project files in the local repo. The save gets a label and version history, including who made the changes, when the changes happened, and what the changes are. But the commit is only local until you push it to the remote repo.

• Push
  This means to upload content from your local repo to your remote repo. You do this periodically when you are working and also when you’ve finished your draft and want prepare it for review.

• Pull request
  Often shortened to PR, this is a request to merge your branch into the main branch. PRs are where formal reviews happen: your teammates can comment on your changes, suggest edits, and approve the work before it becomes part of the main repo.

• Merge
  The process of taking changes from one branch and adding them to another branch. Once your changes are reviewed and approved, your branch will be merged into the publishing branch (usually through the Pull Request process on GitHub, either by you or a project manager).

This can seem a bit daunting at first, but as you start to understand the workflow better, the terms begin to stick. I’m not going to tell you how many times I had to go over staging and commit to get it to sink in!

Project setup

Typically, a documentation project has a branch (version) for the current published content. This is a protected branch that you should not update directly unless:

• Your changes have been reviewed and approved

• It is the right time to update the publishing branch.

The publishing branch is often called main, but some teams use a different branch, like release or production for publishing the documentation.

When you start working on a piece of content, it’s good practice to create your own branch from the publishing branch. That way, you can work on changes in your own branch without affecting the publishing branch or interfering with your teammates’ work.

Common workflow for technical writing in Git

Okay, so that’s the workflow you’ll likely follow. I’ll cover each step in more detail, including how to actually do the work, in later articles.