Publication Integrity

by Robin Shobbrook

Welcome to the third blog in this series on Publication Integrity. This time we'll highlight some aspects of updating documents which often don't get proper consideration in the busy world of technical information management and publication.

Part 3

Imagine the scenario. You notice an error, or need to change a whole section, in an important technical publication. You want to get it done quickly so all your users/
customers have the correct, up-to-date information. You authorise an editor to make
the change.

But, in today's highly regulated and competitive environment, you also really need to consider the following before you proceed: accuracy, consistency, layout and corporate standards.


Obviously you want your changed section to contain accurate information, so it makes sense to get it reviewed. You'll probably also need to get it approved before publication.
If you circulate the whole document to a review/approval team, even though you tell them that only one section is changed, they'll usually feel obliged to check the whole document and suggest more changes. Often, just to stamp their own identity on the document. They can prevaricate and loose focus on the job in hand. Sending, just the changed section(s) they were meant to review will get the job done more thoroughly and faster because they won't be distracted by the other parts of the document. Structuring your documents so that they can be broken down into discrete, self-contained sections usually helps alleviate this problem.

Also, if you can send the changed section for review in a standard format, such as XML, which separates content from layout, this helps get the job done more quickly too. Reviewers and editors don't spend valuable time thinking about the layout they only have to make sure the words (and any associated graphics) are correct.

So now you have verified the accuracy of your new content and have the authority to publish it in your document.

Stop for a minute!

Was the previous version (or parts of it) copied into, or replicated in, other documents? Shouldn't they be updated to? And, if possible, wouldn't it be good to make that section of content generic so it could be reused everywhere? With a structured approach, you could make it update all relevant documents automatically. They would then all be kept accurate and up-to-date each time another change is made.


Will the new version of your document be consistent with the previous? Or indeed, with your other technical documents?

A standard approach to the production, look, feel and structure of all your documentation has many benefits.

Using a consistent structure helps users navigate around your documents to find the information they need simply and quickly. They will learn for example that all your publications:

Such a standard structure also helps authors and editors because they are given a set framework to use when creating and updating documents and sections of documents. The content can then be easily broken down into clearly defined 'chunks' so it's simpler to edit, to re-use, to share and to collaborate.

Consistency should also extend to writing styles and terminology. This ensures that collections of content authored and edited by different people, used and reused by different publications, will always appear congruent with the whole.

Layouts and Corporate Standards

How do we ensure our new document looks good, is easy to use and enhances our reputation?

Separating content and layout, as exemplified by the use of DITA and XML, has many benefits, as have already been discussed in previous blogs. It enables authors, editors and reviewers to concentrate on the content without being distracted by what the finished publication will actually look like.

It also means that we can publish different layouts for different purposes and different media: PDF, web pages, help files, eBooks, layouts for mobile devices of assorted sizes and to be used in various environments. And it can all be done from the same content source and much more speedily than by conventional publishing processes.

Perhaps most importantly, it means we can develop and enforce corporate style for things like:

No more relying on what each author thinks looks most attractive!

This means the user always sees consistently formatted information. Your documents look good and are easy to use. All this enhances your brand identity and perceptions of proficiency and excellence.

So, our objectives should be ...

Of course, most of this CAN be done without using structured documentation. But that's a bit like using a wooden drawing board in the age of CAD/CAM systems. It requires a lot more management, discipline, tedious manual input and checking. It takes more time and is ultimately less reliable.

In the final blog in this series, we look at publishing processes and publication dissemination.

 Back to top
Back to BLOG page ...







Robin Shobbrook is Test and Quality Manager at Koala