By Morgan Hancock
I’d be lying if I said the potential puns didn’t fuel my passion for Git at least a little bit. I titled my speaking proposals “Git Ready!” and my training courses “Git Started!” I’d often catch myself saying, “Do you git it?”
Cheesy, low-hanging puns aside, six months ago Git was a foreign source control system to the technical writing team at Bazaarvoice, a business-to-business software company. We were using SVN (Subversion), which we still use for some products. However, the software development teams at Bazaarvoice had long abandoned SVN for Git. Many developers prefer Git because it’s a distributed source control system that tracks a repository’s history, not just differences between file versions. However, tools and processes for developers don’t always work for technical writers, but still I wondered, would Git?
Exploring Git
Git is a distributed source control system that tracks a repository’s history, not just file changes, but what exactly does that mean?
In SVN, a commit added changes to the repository for specified files. In Git, a commit is a snapshot of the repository. When you view a Git commit, you won’t just see the files that changed. You’ll see what the entire repository looked that at that point in time. So a Git commit captures changes to files but also records unchanged files.
This method of tracking changes is beneficial to software developers when an error or bug breaks their code because Git allows them to easily roll back their repository to a safe commit. They don’t need to revert a ton of individual commits to return stability; they can simply roll their branch back to the last stable commit.
My writing team could benefit from this, too. We recently updated the name of a feature and republished the knowledge base (KB), only to be told the next day that the name change wouldn’t take effect for a few weeks. We had to revert each file we touched before we could rebuild. If we had been using Git, we could have simply reverted to the previous, stable commit and republished. We could have also maintained the changes we had made and deployed them when the name change took effect, instead of having to manually apply the changes a second time, doubling our work.
An increasing number of frustrations combined with dwindling SVN support at our company made my team realize we needed to change our source control system. We decided to mirror our developers and migrate to Git.
Workflow
Before we actually moved any files to Git, we needed to identify a workflow that meshed with our processes. In our SVN workflow, we developed content locally, used PDFs, HTML, or MadCap Flare review packages for reviews, and committed changes to the SVN repository when ready to publish. We knew our SVN workflow wouldn’t directly translate to Git, so we researched several popular Git workflows. Ultimately, we decided that GitHub Flow best met our needs and would be easy to follow.
GitHub Flow (now our workflow) relies on a golden rule—the master branch is always deployable. This means that the master branch is always stable and only contains content ready for publication. Publishing from this branch is always safe. We consider everything in the master branch published or about to be published.
To create new documents or edit existing content, a writer branches off of master and develops in that new branch. The writer commits changes locally and pushes that branch and those commits to the remote repository regularly. To collaborate, other writers can work in that branch and share new commits, or create their own branch and submit a pull request to ask the other writer to merge their commits into that development branch.
In addition to our traditional review methods—creating a PDF for review or sharing a MadCap Flare review package—Git gave us additional avenues for reviews and collaboration. We can send SMEs to view changes in a specific commit on GitHub. At the end of our review process, we submit a pull request to merge our development branch into the master branch. Instead of having a traditional lead review, we can ask our lead to view the pull request, review our changes, make comments, give feedback, and accept the pull request if approved or after implementing the new feedback. This streamlines our process quite a bit and has improved efficiency. Some writers prefer the traditional review methods, but others have embraced the GitHub-powered alternatives. Either way, Git has provided additional options that our team can choose when appropriate.
However, before we actually used this new workflow, we had to face the steep uphill battle of learning how Git works and how to use it.
Training
As the most easily excited person on my team, I enthusiastically volunteered to develop Git training for our team. I had no idea what a deep abyss I was about to plunge into.
The Internet is overflowing with amazing and detailed resources for Git. But almost all of the helpful resources are for developers and coders, people not like me and definitely not like my team. I couldn’t just corral a bunch of links and tell my team to start reading. We’d have been back home with SVN almost instantly. So I had to learn Git for real and filter out the noise before I could train my teammates on it.
Here’s the thing about Git—it’s a very powerful source control tool for developers. There are so many commands that a developer may need that a technical writer would have no use for. I didn’t want to overwhelm my team with all the knowledge! So I had to sift through commands and concepts and figure out what my team really needed to know and what knowledge would only be useful in rare situations.
I read Atlassian’s Git guide, a Git for beginner’s guide, and another guide from Think Like (a) Git. I watched a video called Git for Ages 4 And Up. While great resources that were newbie-friendly, these were still filled with concepts just not relevant to a technical writer.
After consuming everything Git-related and finally understanding it, I was able to figure out what information would be most useful to my team and develop training. Basically, the training ended up covering the common commands we’d use in our workflow and basic Git concepts like branching, merging, and tracking a repository’s history instead of a file’s changes.
Tools
Moving to Git affected the tools we use. We author our content in MadCap Flare 11, which offers integrated support for Git. We used this feature at first, but quickly decided to not bind our Git projects to source control in Flare. We encountered many issues with committing and merging changes, so we decided to separate source control from our authoring tool.
To track our Flare content with Git, we simply added each Flare project to a Git repository. We added some Flare project components to our .gitignore file, such as the Output and Analyzer folders and files Flare generates. We then authored our content within Flare and used other tools to handle source control.
We use both GitHub Desktop, a graphical user interface (GUI), and Git Shell, a command-line interface (CLI). An all-encompassing GUI client doesn’t exist for Git, meaning you can’t completely avoid the command line. GUI clients for Windows machines offer fewer commands in the interface, as we’ve sometimes painfully experienced with GitHub Desktop. However, we can accomplish most tasks in our workflow within the GUI. Though once you learn the commands, the command line is a very powerful and efficient tool that technical writers shouldn’t fear.
I’m glad my team has started using Git. The ease of branching has sparked exploration and innovation. We’re able to explore new writing styles, topic structures, and designs without worrying what to do if an exploration or wild idea takes a wrong turn.
Although Git has a steep learning curve, the best way to learn is to dive in and give it a try. Because Git tracks history, not individual changes, it’s really hard to make disastrous, incurable mistakes. You can almost always go back to a better place in history and start again. Who wouldn’t love that?
MORGAN HANCOCK (morgan.hancock@bazaarvoice.com) is a technical writer at Bazaarvoice in Austin, TX. She graduated from the University of North Texas in 2013 with a Master’s degree in professional and technical communication. You can check out some of her technical explorations on Codepen (http://codepen.io/mhancock) and GitHub (https://github.com/morganhancock).
