Re: Using git For Managing DITA Content

Chris Papademetrious

It's great to hear how other companies are using DITA+Git! Thanks to everyone that shared detailed writeups.

We are also using Git for our documentation, and it works well. We have three Git repos that contain roughly 20k DITA topic files each (plus image files and whatnot), servicing aboout 50 writers worldwide. The repos are hosted on a free Gitlab instance run by our IT department.

Our writers use Git entirely through Oxygen's excellent Git plugin; they do not use any other Git client software. The plugin provides plenty of functionality for all the usual tasks (staging/pushing, browsing history, resolving conflicts, switching branches), plus it gets regular updates that bring even more features.

The software we document has a regular release cadence. We have multiple releases in customer use at a time. When R&D implements a feature in a particular release, they implement it in that release plus all subsequent releases. To match this in documentation, I run a weekly cron job that performs cascaded forward merges across the release branches. When a writer documents a feature in a release, it becomes documented in that release plus all subsequent releases.

Sometimes, conflicts occur during these branch merges. I'm the "Git person", so the STDERR output from the cron job merge failure goes to me. I'm confortable with the Git command line, so I fix these merge conflicts outside of Oxygen. My laptop runs Windows 10, but I work with Git within an Ubuntu instance running under Windows Subsystem for Linux (WSL).

We store both books and release notes in the Git repos. Releases notes are a bit of a mess because they are stored in release-named directories that keep accumulating. Some day I'll need to do something about that.

Our Git repos also contain the Oxygen project file (.xpr) plus all the associated schema/framework/etc. files. This allows me to roll out updates to the Oxygen authoring environment transparently to the writers. I can even push out DITA-OT plugin updates, and the writers automatically receive and use them.

A couple years ago, I took Eliot's advice to "keyref all the things". (Well, almost everything - we keyref all topics, but image files local to a topic are still referenced directly.) At first it felt overly complicated, but now I appreciate the wisdom of it. Writers can freely commit content restructuring to Git, and references to that content (within-book and cross-book) remain unaffected.

If you've been meaning to "keyref all the things," note that Oxygen 24.0 provides a new "Define keys for all topic references" refactoring operation that (1) adds @keydef definitions to your maps, and (2) converts @href references to @keyref in your topics accordingly. (It does not support nested-subtopic <topic> elements in a topic file, but we seem to be the only company doing this.) This refactoring operation is a great opportunity to move to key-based references.

If you decide to "keyref all the things" in Oxygen, be sure to enable "Use the file name as the value of the 'keys' attribute" in Preferences > DITA > Maps. This instructs Oxygen to automatically create keys for any new topics you create. When you add cross-references, Oxygen is smart enough to automatically use @keyref instead of @href if the reference is reachable by key.

We do have content that I manually share across our three Git repos. Evaluating the Oxygen Git plugin's support for submodules is on my to-do list...

 - Chris

Join to automatically receive all group messages.