July 1, 2023

Calming the Cacophony of Content Changes

If there’s one thing that never changes, it’s that everything changes. The ancient Greek philosopher Heraclitus saw the world as constantly in flux and is often quoted as coining the phrase “Change is the only constant.” The same could be said to be true about technical documentation. No sooner is one release complete before you’re working on the next and everything that seemed to be stable starts to change again.

But how can you be sure that you have control over the changes that are being made? How can you know that the latest update contains only the necessary changes without unintended changes slipping in? How can you evidence changes requested by a regulator in a reliable, satisfactory, traceable way?

At DeltaXML, we’re passionate about finding, understanding, and managing change so we’ve come up with some top tips for calming the cacophony of changing content.

1. Know your change stakeholders.

Just as you need to think about whom you’re writing for when you produce documentation, you should also be aware of who needs to see changes. It isn’t always appropriate for everyone to have a view of every update that’s made to your content. But for certain stakeholders, seeing exactly how a document has changed can provide extra value and make their job that much easier. So, think about how change might be useful for authors, editors, reviewers, subject matter experts, auditors, customers, and any other content stakeholders you might have. How might change provide extra value to them or make their job that little bit easier?

2. Build change identification into your content workflow.

We’re used to automating all sorts of tasks when it comes to our content: spell-checking and grammar-checking, compliance with style guides and branding guidelines, readability and comprehensibility – the list goes on. If understanding change is useful for your stakeholders, then it stands to reason that carrying out automated comparison as a matter of course for new content versions is a good idea. And even better than simply identifying change but representing it within your source (or at least a copy of your source within the toolchain) allows you to make use of change markup in different ways. More on that later.

3. Be flexible about which changes you publish

While change tracking is useful for viewing changes over a short period of time, it isn’t great at showing change across a large timespan of multiple document versions. It’s also more of a challenge to publish the changes using your normal publishing pipeline. So, if you want to add flexibility about the scope for which you allow stakeholders to view their changes, comparison gives you greater flexibility. You can just as easily find the change between version three and four as you can between one and four, for example.

4. Tailor your change output to your stakeholders.

Even change can be reused. You’re used to reusing content so why not reuse change as well? Having identified it once and represented it in the source, it can be repurposed to produce different outputs. Because stakeholders view content in different formats and environments, it makes sense to tailor the view of changes for each of them. For example, an author working in an editing environment might want to see a ‘track changes’ view built into the editor using. A subject matter expert accustomed to reviewing content as a PDF would prefer a redline document. An end user reading documentation in a browser may find it useful to dynamically switch between a plain view and a ‘change’ view. If you pick the right tool, you can find changes once and present them in different ways, just like you do with the content itself.

5. Be creative.

There’s no reason for changes to be boring. Have some fun with how you present it! For example, in an update to our new SVG comparison feature that’s recently been added to our DITA and DocBook comparison tools, we’re experimenting with using animation to highlight how images have changed. If you’re publishing your content to a dynamic output format, make use of its flexibility to provide interesting ways to view change. Using animation or on-hover popups to go into greater detail can keep the page clutter-free while still giving rich detail about what changes have occurred.

It’ll come as no surprise to discover that DeltaXML’s suite of comparison tools for XML, DITA, DocBook, and more can help you out with all of this. Featuring customizable comparison as well as built-in capabilities to intelligently compare CALS (and HTML) tables, MathML, SVG, and much more, our tools are designed for integration into your content workflow.

If you’d like to find out more visit where you can sign up for a 14-day trial.