Using Git to Manage Software Documentation

Why technical writers should use Git, and How

Word processors (Microsoft Word, Google Docs, Evernote, etc.) are all fine products that do what they're meant to do. Here, however, I'll make the case that technical writers and developers should switch from word processors to Git when writing documentation.

This mindset can be described as "documentation as code." Documentation should be part of the product itself, not an afterthought. Using Git and static site generators, a technical writer can collaborate with developers to create documentation that is detailed, accurate, and user-friendly.

If you're a technical writer or other non-developer who is afraid to move forward, don't be. Anyone can learn Git, and a couple of hours can bring you up to speed with one of the most powerful and ubiquitous development tools in use today.

What is Git?

You may know that Git is a version control system (VCS). Think of it like a more powerful version of Microsoft Word's "Track Changes," or Google Docs' "Suggestion" feature. Git gives you precise control over your documents, and lets you backup and restore them from any point.
 
I recommend you skim through this primer from the Git website. Understanding the Git workflow is also essential.
 

Setup and Basic Use

The Command Line
There are several ways to use Git. We recommend using the command line (it's easier than it looks).

Not just for hackers on TV

Familiarize yourself with the command line using this tutorial from Team Treehouse. If you happen to be using Windows, you should employ Git Bash so that you can use the same commands as Mac/Linux users.

Alternatively, you can install a GIT GUI (graphical user interface) like GitKraken, SourceTree, or Github Desktop that lets you avoid the terminal altogether. This guide will cover the command line, because it allows for better speed and focus.

Git Installation & Configuration

Setting up Git is easy, and there are dozens of tutorials out there. Check out GitHub's guide for installation and initial setup.

Commands

Once Git is installed, you need to learn a few essential commands. This other tutorial from Github can help you quickly master the basics of Git.

If you're still totally lost, don't give up. There are plenty of Youtube playlists devoted to teaching Git, and GitHub even has entire classes for beginners.

Tools for Technical Writers

Once you've mastered the Git workflow, learned how to manage remotes, and learned the basic commands (Add, Commit, Push, Pull, Branch, and Merge), you can start using Git to manage your documentation.

Keeping documentation in your central repository makes it easier to grow it alongside development, which is ideal for creating accurate and useful documentation. It also lets you easily host your documentation using a service like Github pages.

Useful Commands

Diff
The git diff command is useful for writers because it lets you see the differences between two different repositories, commits, or branches.

Say that you start writing some documentation. After initializing a new repository and checking out a new branch (git checkout -b intro), you write up an introduction. Once you're done for the moment, you use git commit -m 'Add introduction' to check in your work.

The next day, you come back and start making some line edits. You check out a new branch called intro_edits. You make some corrections and clarifications and make another commit.

Before merging the new version with the unedited one, you can use git diff to see where you made changes and make sure everything is the way you want it. It's easy to see where you have made edits, and what you still might have left to fix. With Git, the editing process becomes a lot more transparent and organized.

Tag
Once you've completed a document, your team will likely want to look it over, make suggestions, and add lines. Before you submit, you'll want to tag your document using git tag v1 to show that this is the first version.

Your documentation can even follow the same tags as the project itself. A v0.1 release of the software can come with a v0.1 release of the documentation, keeping everything organized.

Using tags, you can:

1. Submit a v0.1 release
2. Allow for feedback
3. Make changes based on feedback or pull in edited documents
4. Use git diff to see the changes
5. Tag with v0.2
6. Resubmit

With this process, your team can establish a feedback loop to make sure your documentation is up to date at all times. Tagging also lets you go back to older versions and see your progress using git diff. No more guestimation when trying to measure productivity or changes over time.

Note on Aliases

Aliases are customizable shortcuts that let you skip steps when working with Git. To add an alias, all you need to do is add a few lines to your .gitconfig file, which can be found in your root directory (~/.gitconfig).

Below are a few shortcuts for commands you've already learned. Copy and paste the following into your .gitconfig:

[alias]
	co = checkout
	ci = commit
	st = status
	br = branch

Now you can use git st instead of having to type out "status," saving vital seconds.

You can build on these by adding shortcuts to other commands you find yourself using a lot, or file directories that you need to access frequently. (e.g. desk = cd ~/users/username/Desktop).

Static Site Generators

Earlier I mentioned static site generators. These are programs that produce styled HTML pages or PDFs from specialized documents. They allow you to write using a lightweight syntax like ReStructuredTest or MarkDown instead of clunky HTML.

For example, #Hello World (MarkDown) will appear as <h1>Hello World</h1> (HTML) after using a site generator. This process again helps reinforce the "documentation as code" paradigm.

Some generators (like JSdoc) can even parse code for comments and export them automatically. That way if a developer comes up with a workaround to a problem, they can document it in the code while it's fresh, and it will still appear in the full documentation.

Check out this list of open source site generators to find one that suits your needs. Sphinx and Jekyll are popular options.

Once you've written your documentation and exported a simple website, you can host it as a subdomain of your project (e.g. docs.myproject.com), making it readily available to users and developers. This process is also useful when creating user guides, employee handbooks, and even blog posts.

Hopefully, this has convinced you that Git is worth learning for anyone, and that technical documentation should be written in the same environment that software is built in. We've found this process to be effective in creating our own documentation, and we think you should employ it as well.

If you have any questions about using Git for technical documentation, feel free to leave a comment below, or tweet at us @Cuttlesoft.