Re: DITA and Git: Minimizing merge conflicts #version-control #change-management

Kristen James Eberlein

I really appreciate everyone's feedback and advice; it reminds me what a wonderful community we have here! Chris, thanks especially for your most recent e-mail.

Yes, education about Git and Git best practices is critical. It's my current priority to help the team with that.

And to those who are saying "Why hasn't Kris helped them with that already?," I need to say that getting people from 0 to 60 miles/ 100 km a hour is impossible to do overnight. My initial focus was 1) build automation, and 2) ensuring that the DITA source was free of errors. While this is a small help system (1,725 topics), it is loaded with cross references (4,312) and images (1,408). The technical writers badly needed to understand the concept of dependencies, and the cascading effects of deleting or refactoring a topic.

So back to Git and the key issue of technical writers needing to merge some (but not all) of a feature branch into the development branch ... This is a result of how product management operates.

Here is the typical scenario. Product management opens a Jira ticket that focuses on needing to document a new product feature (or change in product architecture) into the documentation. The manager does her best to qualify and negotiate scope, and then assigns the ticket to a technical writer. The technical writer assesses the impact to the existing documentation (and its spaghetti structure); she tries to understand and stage the work as best as possible. The technical writer works hard on improving the content. But approval for deploying the content falls to product management. When they do review the content, they want to tweak words, and so postpone deploying the content for a cycle. Next cycle, they want to cherry pick what is deployed: "I'm good with this; it can go. No, this needs more work; it should wait for another release."

Obviously, this is not a good or sustainable workflow, and changing it is a big priority for the manager. But it's not going to change overnight. Remember that the manager and the technical writers are new to the company and the product. Luckily they are smart and determined.

So I'm still left trying to determine what are the best processes that I can immediately put in place to mitigate pain and churn. I'm leaning towards:

  • Better planning for documentation changes that require feature branches. Can the feature branches be more modular? Better planned and scoped?
  • Increased education about Git best practices, especially around working with feature branches¬†
  • Team guidelines for guidelines for 1) what go should go into a commit, and 2) commit messages
  • Mentoring one of the technical writers as he ramps up to become the team Git expert (already underway)
I'll have to think about whether commiting but not pushing some files and then stashing them is an option. I suspect not, since content in the feature branch needs to pushed in order to generate build artifacts that the stakeholders can download and review.


Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting LLC
+1 919 622-1501; kriseberlein (skype)

Join to automatically receive all group messages.