How to Make Version Control System a Technical Writer’s Best Friend

The February 2016 meeting featured Richard Mateosian, who discussed version control systems. This meeting summary was written by Calvin Yee.

As technical writers, you will encounter version control systems (VCS). If you’re anything like me, a VCS can be confusing and challenging to use. At the February 2016 STC-SF chapter meeting, our speaker, Richard Mateosian, demystified how a VCS works and how using it well help you be a better member of a software development team.

Mr. Mateosian said that there are parallels between what technical writers and developers do when creating a software product. For example:

  • Developers build software components and writers create topics.
  • Developers build the software so it can be tested and writers build documents so they can be reviewed.

Because the processes are similar, any tools that developers and writers can share for creating the product is a good thing.

One of these tools that’s shared is a VCS repository (“repo”). A repo mainly handles text files. Developers handle files that contain code while writers handle files that contain topics or mapping information.

How a Repo Works

A repo provides the following features that are crucial to developing complex software:

  • Keeps track of current and older versions of your files.
  • Keeps track of related files for a project. This is generally the source files for building software packages or documents.
  • Allows for the creation of a Master repo and branches within a repo to manage the complexity of a development project.
  • Includes tools for manipulating files such as checking files in and out, merging files, comparing file versions and keeping a log of changes.
  • Integrates with other tools.
    NOTE: Repos handle text files the best (for diffs and merges), but they don’t handle non-text files as well (such as binary objects, or proprietary files like FrameMaker) nor do they understand the contents of a file nor do they perform component content management (CCM).

Using a Repo

The basic workflow steps for using a repo are:

  1. Maintain a local copy of the repo on your machine.
  2. Keep the local copy in sync with the master repo.
  3. Make your changes and test them locally.
  4. Commit the changes from the local copy of the repo to the master repo.
    NOTE: Committing a file to a repo is a formal way to get the files into the build system to create the software product.

Types of Repos

A VCS repo is either centralized or distributed. The differences are:

  • To use a centralized VCS, you must be connected to the central server to be able to do anything with a file. (Perforce is an example of a centralized VCS.)
  • To use a distributed VCS, you do not need to be connected to the central server (or “master repository”) to make changes to a file. The reason is for a distributed VCS, you are working on a complete copy of the master repository that you downloaded on your local machine. Thus, you can make all the changes you want to a file, create a branch, and so forth without having to be connected to a centralized server. (Git is an example of a distributed VCS. In Git, making a complete copy of a master repo is called “cloning the repo”.)

Features of a Repo

There are three main features that a repo provides:

1. Locking Files

Repos have a locking mechanism to restrict access to a file while it is worked on. The locking mechanism prevents someone else from overwriting your changes or yourself overwriting someone else’s changes in the same file. Repos offer two types of locking mechanisms:

  • Pessimistic locking – You check out a file, which then locks out all other users from editing it. Once you’ve made your changes and check the file back in, then another person can check it out. The assumption is “nothing good will happen if more than one person works on a file at a time”. Subversion and Perforce use this type of locking.
  • Optimistic locking – You check out a file and tells others that you’re working on it without locking it. The assumption is that most changes don’t interfere with each other. Git uses this type of locking.

2. Creating a Branch

To allow for different parts of the software to be developed in parallel, a repo allows you to create branches. This allows different users to work on their part without stepping on other’s work.

This is the workflow for creating a branch in Git:

  1. Create a branch & track it on the “origin” repo.
    NOTE: The term “origin” refers to the location where you made a copy of the source repository.
  2. Make and test changes locally.
  3. Sync the local repo with the origin repo and issue a pull request.
  4. Submitter and reviewers discuss the changes until everyone says LGTM (“looks good to me”).
  5. An authorized user (could be you) merges your branch into the master (the origin repository).
  6. You delete your branch.

Users like Git because it’s easy to create a branch with relatively low overhead (compared to a system like Perforce). In Git, you can think of a branch as a list of pointers. Because you are working with a local copy of a repository, you can do endless pulls from the master repo. This makes it easier to merge the changes back into the master repo.

The main difference between Git and GitHub is that Git is strictly a VCS and GitHub is a website that houses multitudes of projects.

NOTE: A “pull request” is a GitHub-specific review mechanism. It is a way to get reviewers to look at the code or file before it is merged into the master repo. (Reviewers typically receive an email notification of the pull request.)

TIP: To view all the branches for a Git repo, use “git branch”.

3. Performing Merges

When you want to bring the different branches together, you perform a merge. Merging is about putting changes from a branch back into a master copy. The workflow for merging is:

  1. Check out the file.
  2. Make changes.
  3. Check it in.
  4. If the VCS sees a conflict, use its tools to resolve it. The tools let you see both persons’ changes.

Some participants offered their observations about handling merge conflicts:

  • Ask other users roll back their changes so that only the correct changes go through.
  • Ask another human to review a merge conflict. The VCS may not always be correct when it generates a merge conflict. For example, if a user checked out a file but never checked it back in, this can generate a merge conflict.
  • Communicate with your co-workers to coordinate the changes made in a file to minimize merge conflicts.

Other Helpful Tools for the Developer Environment

DITA

If your company wants to implement a DITA system but does not have the budget to implement it, there are options to implement a smaller DITA-compliant system. The “bare bones” for this system are:

  • oXygenXML for editing and publishing (this is a “paid” tool that is DITA-aware). This tool keeps track of the DITA maps.
  • Jenkins (formerly called “Hudson” because Oracle trademarked this name) for automating the build process. Jenkins is a Java-based tool.
  • Git for managing content and version control.
  • DITA Open Toolkit for generating the documentation output.

Source: Eliot Kimber, DITA for Practitioners

Issue Trackers

Because creating software is a complex endeavor, you need to track issues to keep the product development on schedule. Issue trackers can be specialized such as ZenDesk for support tracking. JIRA or Bugzilla for developer-issue tracking. However, all these tools share the same capabilities, which is the ability to track tasks, defects and comments about them.

This is the issue tracking workflow:

  • Someone reports an issue.
  • People Comment.
  • Assign issue to someone.
  • Make changes and others review and comment.
  • Designated reviewer closes the issue.

Summary

Mr. Mateosian emphasized that using the software development tools is not enough by itself. To become a more effective member of the development team, he offered the following tips:

  • Be an active part of the team!
  • Understand the process you’re a part of (you must make yourself a part of it—even if you don’t feel like it!)
  • Be an active participant in all the communication spaces (chat, email, Slack—which is another chat mechanism where you set up a group so everyone can communicate in one place).
  • Take charge of documentation review—make it efficient. The bottom line is don’t waste the developer’s time.

About the Speaker

Richard Mateosian is a fellow of STC and has extensive experience as programmer. His road to becoming an API technical writer was a very winding road. He began as a mathematician, then became a developer, followed by a technical marketer, before becoming an API technical writer. If you have further questions or comments for Richard, you can reach him at xrmxrm@gmail.com.

Link to the slides from Richard’s presentation.

Advertisements

One thought on “How to Make Version Control System a Technical Writer’s Best Friend

  1. Understanding technology is something that most of us have a hard time with. It’s important to figure it out though and get an idea of how we can use it in our everyday lives. I’m grateful for these services and all that they do for us.

    Like

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