Posted20 October 2015
byPhil G. Fearon

Launch of XMLFlow – softening the scream?

Posted20 October 2015
byPhil G. Fearon

Judging not only from my own experience but from many social media posts such as Tina Henderson’s tweet shown below, the review and release process for the creation of content for articles or books can be a painful experience:

Tina Henderson’s tweet showing a lot of edits to a paper. Her tweet reads: Pardon me while I go screaming into the next room.

The version control approach

To solve the document review and maintenance problem, many software developers are now looking at how we can use modern resources such as distributed version control systems, like Git or Mercurial to improve things for writers. Many of these efforts come from developers who have gone on to become authors covering specialist content in the area they work.

Because code is managed as well-formatted lines of text, the line-by-line comparison methods used for managing different versions can be reasonably effective for version control, so the thinking is – why can’t it work for narrative content also?

This is probably great for other developers who know all about feature branches and merges and understand repos and clones, and choose a line-based format such as one of the markdown variants, but (as a former writer turned coder) I’m not convinced it is the way forward for writers.

As an example, here’s a link to a writing, the future, take 2 by @bbirdman promoting one approach in response to Scott Chacon’s (from GitHub) Living the Future of Technical Writing.

Writers in general won’t see content creation as something akin to code writing, they, or their publishers, are also likely to want structure and semantics that do not easily break down into lines of text. Moreover, they know that most errors arising from edits have to be spotted by eye, they can not be picked up by a test-suite, a style-checker or a code compiler.

Writing with DITA

This XML based document markup format, is a total contrast to the markdown-variant approach for authoring linked to earlier, but it is becoming increasingly popular in many publishing environments – its main emphasis is on providing structure along with flexible capabilities for the reuse of content.

XMLFlow – a ‘living version’ approach

[Update: XMLFlow was demonstrated at the XMLLondon 2015 conference]

Screenshot of XMLFlow

XMLFlow is a web app I’m developing (and first released today) that exploits DeltaXML’s DITA Merge product running on a host web server. It can merge multiple DITA documents that have been modified ‘offline’ back into a single valid DITA document ready for further processing or publishing.

This kind of document merge is frequently difficult for the person tasked with resolving the changes back into a single document. This is because of the high probability of conflicting changes occurring when the document has been modified in a concurrent way (not necessarily the most effective way to work – but inevitable in many situations).

By pulling all changes into a single simplified document view (not full WYSYWIG), and showing dynamically where changes come from and how they can be characterised, XMLFlow aims to greatly improve the efficiency and quality of this process. Changes are either accepted, rejected or deferred in a ‘Working Merge’ that can be stored for sharing or working on later.

Once all changes have been resolved they are finalized back into a ‘pure’ DITA document – with the final version of the working merge containing a history of all review decisions – to meet the needs of any formal document review process.

Next Steps

The direction this app takes will depend on feedback or discussion, so please post any comments here. XMLFlow mainly serves as a study on how one important and critical task in the document review process can be improved, but in a way that fits in with existing practices.

XMLFlow is predominantly a demonstration of one of many possible front-end solutions for exploiting what DeltaXML’s DITA Merge product can do to assist in the DITA writer’s workflow. But to be effective in this role, I’ve tried to include all the basic functionality to make it usable in its own right. I’ve concentrated on DITA, because that’s what DITA Merge specialises in – however support for more document formats is possible in future.