Git for Technical Writers—Dropping the Bucket
Traditional source control systems use the “bucket” as a metaphor—you check out a “bucket” of content that’s all yours until you check it in. Git, however, is a distributed system, and isn’t content management so much as change management, so it behaves differently than we expect. This workshop provides a mental model to replace the bucket and provides “safety first” procedures to help you stay out of Git Jail. If you’ve looked at Git Basics and felt confused, or if you struggle with Git surprises, this workshop is for you. No experience necessary.
Workshop leader: Mysti Berry, Okta
Mysti Berry has been writing technical documentation for over 25 years. After a decade with DITA/XML, she pivoted to git/Markdown, and hasn’t looked back.
When: Saturday 21 January 2017, 8:30-10:30 AM
Workshop prep instructions
To make sure we are ready to get started, please use the following instructions to install git on your laptop and make sure you can find our sample repository (it’s empty right now).
First: Install git:
- Follow the instructions here: downloadsIf you have trouble, read the readme.txt file for “gotchas”, or reach out to the instructor, Mysti Berry, at firstname.lastname@example.org. She may be able to help you out.
- Open a terminal window, move to the git directory, and type the following:git —version
- If the terminal window shows your git version number, you installed git! If you see anything else, something has gone awry. You can email Mysti, or wait for class.
Second: To visit the repository (currently empty), visit MystiAnne
Third: Optionally, you can sign up for a free account in GitHub, the tool some people use to manage their git activity: join?source=header
Note: If you don’t have a laptop, or don’t plan to do the exercises in class, don’t worry, you can watch along with someone else, or follow the instructor as she does the exercises.
An interview with the presenter
by Li-At Rathbun, your TC Camp Roving Reporter
Ever get lost trying to follow changes in a Git document? Mysti Berry provides a road map that can always get us back on track!
Li-At: Who should attend this January 21 workshop?
Mysti: Anyone who knows that Git is on the horizon for them as source control, or anyone who is currently using Git and made a mysterious mistake they didn’t understand.
Li-At: What is Git?
Mysti: People call Git a “distributed source control,” which means people working all over the globe can edit the exact files at the exact time and they won’t get in trouble with each other.
It’s truly distributed files with shared ownership: no one really controls the content. You can’t lock it. You can’t be the person whose check-ins are always believed over everyone else’s. Anyone can change what you’ve done. (Of course, there’s always a review process.)
So when a writer is trying to figure out what they’ve done, it can sometimes be confusing. But that confusion can always be cleared up by keeping a few regular practices in mind when you’re using it.
Li-At: Why should technical communicators care about Git?
Mysti: Git can be used for all kinds of content, but most of the advantages are for people writing developer content. It’s used widely in the development community. It’s open source, it seems pretty robust, and developers like to use it.
There are some advantages to using the same tool for your files as the developers use for their code files, including:
- The developers understand the review environment.
- The developers can write some of the content themselves (specifically, some of the techie stuff, like the API endpoints information and such).
- It’s an all-in-one-place for your authoring, reviewing, and distributing tools.
Li-At: Okay, so this is TC Camp. So my next question is what’s your favorite camping spot?
Mysti: Probably Yosemite. That’s the sentimental favorite. But I’m of the age where hotel camping is my favorite form of camping.
(photo courtesy of Bryce Edwards)