Category: Documentation

When someone is new to MQ, the document they are often told to read is the MQSeries Primer. This is a very short publication from the IBM Redbooks team (the ITSO) that covers the basics of MQ. But it was written in 1999 and has not been updated to take account of new features (or even the new product name).

A few months ago, we got approval to write a new book covering features of the recent MQ 7.1 and 7.5 releases. I’m not going to talk much more about that book in this post, and I’ll let some others from the team comment on it if they wish. The book is still being written, and I expect to see a draft in about a month’s time.

But I decided my participation was also an opportunity to refresh the Primer. We should be able to reuse material: have an introduction to MQ in the full book, but also have it as a standalone Redpiece still referenced from the same URL as the original primer.

I read the 1999 material quickly and thought it would be reasonably simple to modify aspects like the product name or lists of features, and remove obsolete comments such as the one about Y2K compliance. But nothing is ever that simple.

First problem was that the ITSO couldn’t find the source to the document. But at least we could get the text extracted from the PDF and Marcela did a superb job re-tagging the paragraphs so it looked sensible in the authoring environment.

Then I started on the rewrite.

The ITSO has style guidelines for its books, to ensure consistency and clarity. The Primer met very few of those guidelines.

I felt it was not structured in the sequence I would do it. So I’ve been moving and rearranging content.

It had too many specific comments about features that might have been exciting or new in the V5.x releases – those either had to be removed or rewritten to show them as standard features.

And so on …

Right now I’m about half-way through the rewrite, before the editors get their hands on it to “correct” my English spelling into American (another style point that seems more of a rule than a guideline).

I suspect that almost none of the original text will survive this exercise. But I’m not going to denigrate the book – it still has most of the right subjects at the right kind of level. What I originally wanted to do was cosmetic surgery, but we’ve ended up with a brain/body transplant instead. Even so, I hope my rewrite will preserve and respect the intention of what Dieter wrote in 1999. And that we can continue to have a basic introduction to MQ that people find valuable.

This post was last updated on November 27th, 2021 at 03:01 pm