Long Live the infocenter !

I’ve always been a bit scared of infocenters – even though, deep down, I know they’re “just HTML”; they never quite seem that way. Javascript and to-the-pixel object placement is just getting too good these days. You could almost mistake it for a java applet or at least some kind of fancy AJAX application.

But no, it’s just a set of good-old framesets, frames, HTML content, hyperlinks and images, bound together with some javascript eggwhite and stirred vigorously for a few minutes to make the infocenters we know and (some, I hear) love.

However, to make it seem like it’s “alive”, there is a Java servlet lurking back at the server, generating parts of the Infocenter dynamically, including rendering the Table of Contents from a behind-the-scenes XML description, and running search and bookmarks and things like that.

What I became curious about, then, were two things:

  • Could we extract a sub-set of an infocenter and just display that, rather than having to wade through everything we were given? For example, I might only be interested in the administration section of a product, or might only need to know about one component of a toolkit of many components. Having a more navigable and less intimidating sub-set would greatly improve productivity.
  • Rather than having to install an Eclipse infocenter run time on a server to host a set of documentation, is there a way to run it on any plain old HTTPd (e.g. Apache)? I accept that search, bookmarks, and other dynamic features won’t work, but the real information – the useful stuff in the right-hand window, which we use to do our jobs with the products we’re trying to understand; and the all-important navigational Table of Contents structure in the left-hand window – would be available to us “anywhere” we can put an HTTPd.

With a ThinkFriday afternoon ahead of me, I thought I’d see what could be done. And the outcome (to save you having to read the rest of this!) is rather pleasing: Lotus Expeditor micro broker infocenter.

This is a subset of the Lotus Expeditor infocenter containing just the microbroker component, being served as static pages from an Apache web server.

First the information content. The challenge I set was to extract the sections of the Lotus Expeditor documentation which relate to the microbroker component. It has always been a bit of a struggle to find these sections hidden amongst all the other information, as it’s in rather non-obvious places, and somewhat spread around. This means creating a new navigation tree for the left-hand pane of the Infocenter. When you click on a link in the navigation tree, that particular topic of information is loaded into the right-hand window.

However, it quickly became apparent that just picking the microbroker references from the existing nav tree would yield an unsatisfactory result: the topics need to be arranged into a sensible structure so that someone looking for information on how to perform a particular task would be guided to the right information topic. Just picking leaf nodes from the Lotus Expeditor navigation tree would leave us with some oddly dangling information topics.

Fortunately Laura Cowen, a colleague in the Hursley User Technologies department for messaging products, does this for a living, and so was able to separate out the microbroker wheat from the rest of the Expeditor documentation and reorganise the topics into a structure that makes sense out of the context of the bigger Expeditor Toolkit, but also, to be honest, into a much more meaningful and sensible shape for micro broker users

First we needed to recreate the XML which the infocenter runtime server uses to serve up the HTML of the navigation tree. Laura gave me a sample of the XML, which contains the title and URL topic link. From the HTML source of the full Expeditor navigation tree, using a few lines of Perl, I was able to re-create XML stanzas for the entries in the navigation tree. Laura then restructured these into the shape we wanted, throwing out the ones we didn’t want, and adding in extra non-leaf nodes in the tree to achieve the information architecture she wanted to create.

Wave a magic wand, and that XML file becomes a plug-in zip file that can be offered-up to an infocenter run time, and the resulting HTML content viewed. After some iterative reviews with potential future users of the micobroker infocenter, we finalised a navigation tree that balanced usability with not having to create new information topics, apart from a few placeholders for non-leaf nodes in the new navigation tree.

So far so good – we had an infocenter for just the microbroker component of Expeditor, and it was nicely restructured into a useful information architecture.

Now for phase two of the cunning plan: can we host that on a plain-old HTTPd without the infocenter run time behind it? The information topics (the pages that appear in the right-hand window) are static already, and didn’t need to be rehosted – the existing server for the Lotus Expeditor product documentation does a perfectly good job of serving up those HTML pages. It’s the rest of the Infocenter, the multiple nested framesets which make up the Infocenter “app”, and the all-important navigation tree, which are dynamically served, from a set of Java Server Pages (JSPs).

A quick peek at the HTML source revealed that several JSPs were being used with different parameter sets to create different parts of the displayed HTML. These would have to be “flattened” to something that a regular web server could host. A few wgets against the infocenter server produced most of the static HTML we would need, but quite a few URLs needed changing to make them unique when converted to flat filenames. A bit of Perl and a bit of hand editing sorted that lot out.

Then it transpired there is a “basic” and an “advanced” mode which the back-end servlet makes use of to (presumably) support lesser browsers (like wget 😐 ). Having realised what was going on, and a bit of tweaking of the wget parameters to make it pretend to be Firefox, and the “advanced” content came through from the server.

Then we had to bulk get the images – there are lots of little icons for pages, twisties, and various bits of window dressing for the infocenter window structure. All of this was assembled into a directory structure and made visible to an Apache HTTPd.

Et voila! It worked! Very cool! An infocenter for the microbroker running on a straight HTTPd. Flushed with success, we moved it over to MQTT.org (the friendly fan-zine web site for the MQ Telemetry Transport and related products like microbroker). Tried it there…

Didn’t work. Lots of broken links, empty windows and error loading page stuff. Seems the HTTPd on MQTT.org isn’t quite as forgiving as mine: files with a .jsp extension were being served back with the MIME type text/plain rather than text/html, which may not look like much, but makes all the difference. So a set of symlinks of .jsp files to .html files, and another quick wave of a perl script over the HTML files put everything right.

So with an afternoon’s work, we were able to demonstrate to our considerable satisfaction, that we could excise a sub-set of an Infocenter from a larger book, restructure it into a new shape, and take the resulting Infocenter content and flatten it to a set of HTML pages which can be served from a regular HTTP server.

6 thoughts on “Long Live the infocenter !

  1. In the interests of balance, here’s a link to the official IBM Lotus Expeditor Infocenter. You can compare for yourself the accessibility of the microbroker specifics.

    To be fair on the original, the information is largely where you would expect it if you were approaching it from an Expeditor perspective. But I do agree that for the users with more of a microbroker background, the information can be hard to find.

    This is the continual challenge of meeting the requirements placed on a product from subtly different audiences.

    That all said, it is very cool to have a one-stop shop for our docs 🙂

  2. What this really indicates, is that our approach to structuring large amounts of information into a usefully navigable information architecture is fundamentally flawed.
    We need the ability to slice and dice large bodies of (undoubtedly) valuable information into subsets that mere mortals can digest in mind-sized chunks (as Seyour Papert would say), according to their particular interest based on perhaps their role or the task at hand.
    Carving out the microbroker piece was a first foray into this area, which is (hopefully) useful for microbroker fans, but more interestingly has given me a load of additional ideas for further ThinkFriday hackery in this area!

  3. As an information architect in WAS, I agree that pondering the need to modularize our information is a great use of a Think Friday, but have to disagree with “first foray.” There is a TON of great IBM User Technologies and brand development team work going on in this space. The IBM ID community has official, achievable guidelines for modularizing our navigation for reuse. We have the technical framework to let aggregators discover and do something useful with the bit parts. Now there are no excuses; ID teams and others producing info (that’s you, wiki author!) need to JUST DO IT … this is where scheduling the work into product releases becomes vital. Thank you for emphasizing the importance of this behind-the-scens architecture.

    I really can sympathize with our customers and customer-facing personnel, the would-be “modular content reusers,” because this is the stage of “partly there, sometimes there, but not quite there” (my own product docs included). I’ve included the web site for a tool I’d love to demo for anyone trying to put together their own subsetted info center today; it could make it easier than you describe. But, you’re quite right, if you’re saying it’s too difficult if one has to hack the info center to obtain content in modular enough form. At minimum, all docs plug-ins could be downloadable.

    P.S., I also appreciate your “Long live the infocenter” tagline and the fact that it does not seem ironic. There are so many haters out there!

  4. @tricia thanks for your comments. By “first foray”, I very much meant “for me”!
    This project has shown me that there’s more to the pre-canned view that we usually see of the good ol’ infocenter, and I agree that the opportunity is there for the taking. I just hope people will take it before we start to look as archaic as paper manuals.
    Would love to see your demo – will be in touch!

Comments are closed.