Git-based technical writing workflow – notes from a TC Camp session

This week I attended TC Camp 2016 in Santa Clara. In the morning there were a few workshops, one of which was titled “Git-based Technical Communication Workflows”. A team from GitHub walked us through a workflow using Git and GitHub for technical documentation. These are my notes from the session. Any inaccuracy is my mistake, not that of the presenters.

The session covered primarily workflow on GitHub.com, and also touched on using Git on the command line. There was a good variety of Git skill levels amongst the attendees, from people who had never used Git or GitHub, to people who were comfortable using Git on the command line.

The presenters were Jamie Strusz and Jenn Leaver, both from GitHub. Stefan Stölzle was there as technical advisor, and answered plenty of questions from attendees.

Jamie started with an overview of the  traditional GitHub workflow. Then Jenn, a technical writer at GitHub, explained her workflow for technical writing in particular. Here’s the repository that they created during the session, to illustrate the workflow: TCCamp demo repo on GitHub.

Some things I gleaned about a technical writing workflow using Git and GitHub:

  • When a fix or update is required to the documentation, the technical writers start by raising an issue in the help docs repo.
  • Next, the technical writer creates a branch.
  • Jenn’s team occasionally uses “mega branches” used by several technical writers working on a feature. But usually, Jenn just works in her own branch.
  • The term “mega branch” isn’t generally known. I suggested that it’d be great to have some information in the GitHub docs about best practices for managing such a branch. Jenn liked that idea.
  • Jenn’s team uses the Atom text editor.
  • The source format for the documentation is Markdown.
  • A useful tool for converting documentation from HTML to Markdown: pandoc.
  • A question came from the floor about Asciidoc. A few people have heard of it, and Jenn’s team is talking about it too.
  • They make all the changes in the branch, and make commits often.
  • They commit changes locally, then push to the web (that is, sync to the repo on GitHub). Then they make their pull request on the web.
  • Jenn likes to make pull requests (PRs) often, so that she can get feedback quickly. Sometimes she’ll have a PR with 200 changes in it.
  • More about mega branches:
    • Often the mega branch is for development of a doc change over a longer period of time.
    • Create a mega branch, then create branches off that mega branch.
    • Then you create the pull requests off your branch, and do the reviews there.
    • Then eventually push to the mega branch.
  • Jenn does not ever work off the master branch. The team of presenters recommend against working off master, because it’s more difficult to back out changes. GitHub views the master branch as the deployable state – so, it’s production. Therefore, always make changes and do collaboration on a branch. Then merge back into the master branch when ready for pushing to production.
  • A tip: sync with the main repo on GitHub often. In particular, before starting a new branch. Otherwise you’ll have problems later when merging your changes back.
  • Branches can be very small (just fixing a typo, for example) or very large (for a new feature).
  • It’s a good idea to be very descriptive with your commit messages, so that you can figure out which commit to roll back if necessary.
  • For version control within the files, Jenn’s team uses Liquid syntax. They also use Liquid for other conditional publishing, such as selecting enterprise docs only.
  • Git LFS (Large File Storage) is available for uploading large files such as videos, Adobe files, etc. For some of those files, depending on file type, LFS can also help you see the difference between versions. LFS also helps ensure that the large files don’t clutter up your repo.
  • What about conflicts, with multiple people working on the same doc? There are several ways of handling such merge conflicts. Some people use diff tools. Others rely on the comments that Git adds to the files about the conflicts: open the file in an editor, assess the conflicts, and make a decision about which change to accept.
  • Merge conflicts are reasonably rare. They usually happen if someone forgets to sync (“pull”) before starting a branch. Another time when it may happen is if you start working on something, and then the work gets put on hold for a while. When you start up again on that project, you may have conflicts.
  • What to put in a README file on GitHub: A general overview of what’s in the repo, and any vital information such as contributor guidelines.
  • Labels are useful for things like indicating status, such as “ready for review” or “in progress”, or something to indicate the feature under development.
  • The team uses the GitHub issue tracker as a primary communication tool. Even for things like noting when a team member is out of office, or for ordering office items. These issues go into the relevant repo. For example, at GitHub the team orders office items by creating issues in a “Gear” repo (which isn’t available for public viewing).
  • The commands that Jenn uses most often in her technical writing workflow are: git branch, git checkout, git status, git push, git push.
  • All reviews take place in a pull request. The team starts with a comment to start the conversation. They @mention people to bring them into the review, such as the subject matter experts. Before pushing the change to master, someone has to approve, by adding a squirrel emoji.🙂
  • The team uses emojis all over the place in reviews! They use them in place of words.

Jamie created a repository which Jenn used to walk through each stage of the workflow:

  • TCCamp demo repo on GitHub.
  • An issue within the repo’s issue tracker: WIP – Jenn’s doc.
  • A commit.
  • diff shows the changes to a file or files.
  • A pull request. People who are watching the repository will get a notification of the pull request. To request a review by specific colleagues, use an @mention in the comments.
  • If you want someone to focus on a specific area, give them the URL of the relevant commit within the pull request.
  • You can leave a comment on a specific line within the code, as well as comments on the pull request as a whole.

Titbits:

  • GitHub uses an icon of a squirrel (an emoji, :squirrel:) to indicate when reviewers are happy for a change to be shipped. In some forms the squirrel has a name: Heidi. The presenters didn’t know why GitHub uses a squirrel. Does anyone know?
  • We were given a limited-edition GitHub Technical Writer Octocat sticker!

GitHub Technical Writer Octocat

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 24 January 2016, in TC Camp, technical writing and tagged , , , , , , . Bookmark the permalink. 6 Comments.

  1. Hi Sarah,

    Thanks a lot for this wonderful overview – I picked up a few things to weave into my own GitHub doc workflow!

    I was wondering if Jenn mentioned anything about their policy/rules regulating pull requests – things like how many edits are allowed in a single changeset, or whether a pull request can incorporate changes made in multiple docs, etc.

    As for ‘why the squirrel?’, I’d assume it reflects a fast and nimble deployment process at GitHub. The question I’m more interested in is, however, why the fedora? =)

    Regards,
    Vadim

  2. It isn’t a squirrel; it is the Github Octocat. I presume it is because developers tend to love cats🙂.
    Thanks for the great overview. We are currently using SVN, but have plans to move to git.

    Lois (posting from my phone so I cannot easily change the ID).

  3. Great intro to this approach. I wanted to do something like this in my last role but never got the chance, so it’s useful to know should the opportunity come up in the future. Thanks!

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: