Get some training organised if I deemed it to be necessary and finally produce the Help system that my client required.

Step 1: Get hold of the software

Ordering the package was relatively painless. The parcel arrived within two days containing three volumes of manuals and a CD attached to the inside cover of one of the manuals.

The CD-Key arrived by email and Quadralay set up a user account on their website too. I took a look at the site before installing the software and my first impressions were good.Installation was problem free, though it took a significant length of time. I have subsequently replaced that old PC and on the new one installation was reasonably quick. However on running FrameMaker 7.0 after installation it reported an error about swap space. This turned out to be quite misleading and was actually a missing WebWorks Dynamic Linked Library (wwpfm7.dll). Having copied the missing DLL over from the WebWorks Standard files (delivered free with FrameMaker 7.0) I had no further problems.

Note that this problem was caused by my not bothering to install WebWorks Standard when I initially installed FrameMaker 7.0. The WebWorks Professional installation scripts assume that it has been installed.

Step 2: Work out how to use it

I decided that I had better be good and read the Manual before I got started. The three volumes, User Guide, Template Guide and Developer Guide are well presented and seemed to be reasonably complete too. WebWorks provides a set of standard templates for producing various output types.

My client and I agreed prior to acquiring the software that the output would use the WebWorks Help template.I planned to take a training course once I had experimented with the tool the way I personally learn best. So I copied a small document to use as a test for both the system and myself.

The first job my client wanted was a multi-volume manual suite and not really suitable as a test piece. This small test booklet prints up into a 60-70-page book made up of 11 FrameMaker files. I loaded this booklet up and using the WebWorks Help template and the User Guide supplied with WebWorks I generated my first attempt.

Amazingly, it worked first time and produced something that was, although not perfect, certainly better than I could have done on my own with the HTML handbook at my side. There were a fair number of basic customisations needed to make it look more professional. I changed the header and footer and put the company logo into place. This made a vast improvement for almost no effort.

Now aware that the tool is reasonably easy to use, even for a novice, I booked a one-day one-to-one course rather than a programmed 2-day session. I planned to use it to bring me up to speed on the more advanced features that I knew I would need when the time came to produce the full multi-volume suite and other later documents.

I was to find more issues as I continued experimenting with the package in the days prior to the course. I noticed how light the handbook appeared to be on the subject of context-sensitive help. Then I found that is was fully explained in the Template Guide. As the standard template comes with a limited set of heading styles, less than the corporate style used my clients I needed to define more for this template. All this was nicely explained in the documentation. The paragraph styles in use in the paper version needed some work to get them to map successfully to on-line suitable styles. I would have to make some small changes to the source FrameMaker text to get the best out of the tool but nothing too arduous.

I found problems with wanting to have files present in the paper edition but not in the on-line versions but this problem was resolved on the training day.I realised that WebWorks relies upon the consistent naming of files. Best to use .fm for all FrameMaker files. For historical reasons our file names didnt fit this pattern. The original book had been written on a UNIX machine (no need for a .xxx windows suffix) and so we had continued with that even after moving to a PC environment some time ago. A small price to pay I thought so I converted the filenames.

I needed to plan for the multi-volume book too and spotted problems with the cross-reference styles we had in use this needed resolving prior to the main job. Experimenting with ideas to meet the longer-term requirements of my client. I tried to implement a pop-up glossary entry - a useful feature in the multi-volume book. Not difficult to do it seemed but I had a lot of trouble getting the box to pop-up. Eventually I spotted the simple mistake of using the concatenation tag for the first paragraph and the first tag for the continuation paragraph. Unsurprisingly it worked once they were the right way around. I really should Read The Manual!
The positioning of the pop-up window itself seemed to be a little inconsistent and needed checking.

Finally, following the guidance in the manual very carefully, I experimented with the multi-volume book tools. It was not entirely clear what the steps were and I managed to get something to work but I wasnt too happy with either the procedure or the results. I really needed to cover this on the training session since I had a 10-12-volume book to implement as Help quite soon.

So my wish list for the training day had grown to:
1. Multi-volume books
2. Help prettifying the template
3. On-line vs. Paper
4. Index entries and layout of
5. Graphics handling
6. Pop-ups positioning

Step 3: Training

I supplied the trainer with a list of the questions and problems that I had encountered whilst I had experimented pre-course. All of these issues were covered. A workbook was supplied which covered the regular 2-day course. Since most of the basic features were no problem to use we skipped through most of it and looked in detail at a few specific areas.

Most of it was simply a case of clarifying things that I had discovered but the Multi-volume book issue was more fundamental. The details in the handbook were definitely unclear and the mechanism listed in the training worked very well. One thing that became apparent while discussing the multi-volume issues is the amount of processing time the system would require in order to process the FrameMaker files and produce the output Help. I realised that I would finally have the excuse I needed to upgrade my ageing PC.

Step 4: Produce a Help System

Back in the office once more I worked on a small project for my client. Setting up the paragraph styles and translations needed to customise the tools to produce reasonable output for our purpose. This first delivered product was received happily and has been in production for sometime now. The full multi-volume product is still on the drawing board since the product has undergone a full re-think in the intervening period. However the resultant changes will not cause any great problems now that the underlying issues have been resolved.

Conclusions

Well, the experience was not too arduous, I came out of it with the same amount of hair as when I started. I have created one production product and two other projects to draft state, ready for my client to use. I found it generally an easy and reasonably intuitive tool to use. But I do wonder how much the fact that I am an ex-programmer, and thus able to experiment with some understanding of how it might work internally, has helped with the ease with which I picked up the tool.

If you are planning to go along this route be aware of the need for processing power and ensure that your computer is up to the job. If anyone wishes to know more about the process or the WebWorks package and how I am using it I can be contacted at tina@colinade.co.uk.

All articles on the Quality Authors web site are copyright and are the property of the authors, who have asserted their moral rights. For permission to use an article, please contact the author directly.