When it comes to content authoring, DITA is Yamagata Europe’s weapon of choice. However, when you need to collaborate across multiple teams, and when you want to efficiently manage multiple document versions, you will need extra horsepower. At Yamagata Europe, we rely on GitHub, a web-based version control system that is becoming increasingly popular among technical writing teams.

Keeping an overview of all technical writing activities and created documents is no picnic at an organization like Yamagata Europe. In order to efficiently collaborate between colleagues and customers at different locations and to offer qualitative documentation services, we need to be able to:

  • Efficiently control document versions

  • Keep track of updates and reviews

  • Manage multi-lingual versions of various documents

  • Collaborate across different locations

  • Manage publications and document releases

Since we are already working extensively with DITA, you would expect that it makes sense to look at one of the multiple DITA content management systems (CMS) out there. However, for smaller writing projects, a dedicated DITA CMS is not always so cost-efficient.

GitHub as a DITA hosting environment

One of the increasingly popular ways to manage technical documentation is GitHub, a web-based hosting service for version control. GitHub was originally welcomed by software developers as a code hosting platform for version control and collaboration. But today, technical writers have discovered the platform as well as a hosting environment for DITA XML documents. GitHub is an ideal platform for coders and writers alike to work together on projects from anywhere.

In a collaborative environment, it is common for several authors to share and work on the same document. One author might be doing a spelling check, while another author might be adding new paragraphs, etc. ‘Branching’ allows each author to branch out from the original version and isolate their work from others. Later in the process, multiple versions can be merged.

A typical GitHub workflow consists of the following steps:

  • Creating a branch: This is a way of proposing new changes in a document without affecting the master version.

  • Making changes to the document: this includes creating, editing, renaming, moving or deleting files. Making changes in a GitHub environment is also described as committing changes to the branch. A change can also include an additional message to explain why a change was made.

  • Sending a pull request from the branch with the proposed changes in order to start a discussion.

  • Merging the pull request once the changes are approved by all stakeholders and the branch is ready to be merged.

How Yamagata uses GitHub for DITA technical writing  

We believe in the power of GitHub. That is why we also offer this platform to customers who do not have their own CMS. Better yet, we rely on DITA/GitHub for internal document creation as well. We have already used GitHub for various Yamagata projects, including tutorials for our QA Distiller software, SnellSpell software and Nano platform.

A typical GitHub workflow at Yamagata looks like this:

  • Our technical writers start with a copy of the current documentation.

  • A separate branch is created for each job/chapter.

  • Every writer does his/her part of the job (making changes).

  • The work is being revised (sending a pull request).

  • A final version is created (merging the pull request).

  • Our writers use the Oxygen XML Editor to publish to html and Miramo automated publishing software to publish to pdf.

Yes, we love GitHub here at Yamagata. For us, the platform is an ideal way to streamline our document creation process. It offers:  

  • Excellent versioning, collaboration and review features out of the box.

  • Lots of extra features to enable documentation and project management.

  • A widely known and easily adaptable environment.

If you are interested to know how Yamagata Europe can use GitHub to make a difference for your project, let us know.