Publication Integrity

by Robin Shobbrook

Welcome to the second in this short series of blogs on publication integrity in the world of technical information and technical publishing. In this part, we look a little deeper into content management and 'resilience'.

Part 2

Terms

Meanings in the context of this article

Content

Text and images to appear in your published document.

Component

A discrete part of your document's content. For example a topic or
an image.

DITA

The Darwin Information Typing Architecture, based on XML.
Adopted internationally by many industries.
It enables use of standardised structures for information storage,
re-purposing and re-use.

Document

Here we are referring to a collection of DITA topics published as a single 'document'.

Map (DITA)

A DITA 'Map' is a file which determines which topics are used in a given document.

Topic

Here, we are referring to a DITA 'Topic': a DITA file containing a discrete unit of information. Topics are the 'bricks' used to build 'documents'.

XML

The eXtensible Markup Language: independent standard maintained
by the World Wide Web Consortium (W3C).
Separates content from format.

 
         

Content Management

Ever had a problem finding a file? Take for example, a single Word document:

Well, if it's just the one file, given a little systematic thought and detection, you can usually figure it out (eventually!) so it's not much of a problem.

But structured documentation, with all its undoubted benefits, does bring with it the challenge of managing multiple component files for each document: thus raising issues of content management strategy.

Let's take for example a single 100-page document, engineered to meet the DITA (XML) standards. Whilst ending up as a single document, it will inevitably be made up from many individual component files: DITA maps, topics and images maybe over 100 files in total! Added to this, many of these files may be shared with (or be referenced by) one or more other documents. So, instead of keeping tabs on just one file, you now need to manage maybe 150 files and possibly many different versions of each.

To do all this manually, using the Windows file system, is clearly impractical especially if you also have multiple users of the system. So here is where we need the ubiquitous content management system (CMS). Or more precisely, a Component Content Management System (CCMS), designed to handle chunks of information at a
granular level.

Apart from knowing where all our component files are, we need to be able to track changes in content (see previous part of this blog series: Publication Integrity
Part 1, History and Provenance
) and we need to know which versions of which components have been used in which published documents.

It's also vital to manage dependencies between components (e.g. between DITA
topic files):

Once again, I'd recommend a CCMS (as opposed to a CMS) especially designed for structured information. Koala's 'Modulux' is a prime example.
Click here for more about Modulux

Resilience

By 'resilience' we mean how easy is it to recover after a technical issue or when previous versions of documents need to be recovered and re-constructed. Also, how independent is your source content from proprietary software applications and machine operating systems?

Technical Issues, such as hardware or software 'crashes' or even user errors (like deleting files or folders by mistake):

Software Independence:

Operating system independence:

 
In Part 3 of this short series, I look at how structured documentation can be used to improve content accuracy and consistency. Also, how we can use it to apply formal corporate documentation standards.
 

 Back to top
 
Back to BLOG page ...

 

 

 

 

 

 

Robin Shobbrook is Test and Quality Manager at Koala

Is all this apparent complexity
really necessary?

We need to remind ourselves why we're going down the path of structured documentation in the first place. Structuring information in today's technical and commercial environment has become a 'must' because:

And with a capable CCMS,
all the complexity is handled
by the system so it can actually be very simple for users to
work with.