First you need to learn how to use Git, but then you need to find a way to use Git. I.e., Create a workflow that exploits Git’s strengths. This wasn’t obvious to me at first. Heck, I’d never even considered it until someone suggested I read this: A successful Git Branching Model. I’d been struggling with using Git, and I just figured that was a normal part of the learning curve.
Leverage branching
It turns out that you can do some pretty neat things with Git because of the way Git branching works (which is fundamentally different than what you’re used to). I now see branching in Git as its greatest strength. As a technical writer, I use branching in pretty much that same way that the devs use it. The documentation I write is always released in-step with the products (APIs and SDKs) that the docs cover.
Whenever I start a new doc project, I begin by getting an enlistment to the code base.
-
Open a Git bash session. The Git command prompt automatically positions you in your Git Home directory (e.g., /src).
"C:\Program Files (x86)\Git\bin\sh.exe" --login -i -
Get an enlistment to the project source code repository (i.e., Clone it locally). Here’s an example:
git clone git@git.c11.3rdParty.com:android_mobile_verification.git -
Change directories; move down from the HOME directory to the project directory. Notice that you currently have the Master branch checked out.
cd android_mobile_verification/ -
Switch to the develop branch because that’s where all of the new bits are staged for the dev’s code, and for your new doc content.
git checkout develop -
Fork off of (i.e., create a new branch off of) develop to use as a baseline branch for doc work that your team can then merge in with their latest code bits. My team and I settled on the convention of the branch name feature/api_doc.
git branch --track -l feature/api_doc
Note: the use of the track option to mark the start-point branch as “upstream” from the new branch. The track needs two dashes. The l switch is used to create the branch’s reflog. This activates recording of all changes made to the branch ref. This allows me to create a paper trail (isolate and capture each change in a uniqe commit) for each and every change that I make to the docs.
-
Checkout your new feature/api_doc branch.
git checkout feature/api_doc -
Fork off of (see Fork a repo) feature/api_doc for authoring content for a specific version of the docs (e.g., maybe the devs added a new feature for the next version of the product). I usually give the new branch a name that indicates the product release number that the new content is for, but if I have no idea what that will be, then I choose something that appropriately indicates the state of the docs.
git branch --track -l initial -
Checkout your new working branch.
git checkout initial -
Author new content. I.e., Add, revise, and/or delete content.
-
Merge the content into your baseline branch. As the product evolves, and the devs add new features, this step updates existing content with new content. When I complete the content, and after it’s been reviewd, and I’ve incorporated the revisions, I switch back to the feature/api_doc branch, and then merge the new content into it (i.e., I execute a git merge coming from the branch I was just in). These particular command options ensure that each of the iindividual commit ref log entries from the work I did in the other branch appear in the feature/api_doc as well (otherwise, they appear as just one merge commit).
git merge -s recursive -X theirs initial
-
All that needs to happen now is to make sure that the new content is merged into the devs new code bits. This entails two steps:
- Push the content upstream.
- Send a Pull Request (e-mail) to the Release Management team.