Creating help files

I do not often write on the weekends however today is different.

As all software vendors we need to produce documentation for our users, and today I have been looking at how we can convert our Microsoft Word based documents into something more "online and real time".

My requirements for a tool/process are fairly straight forward:-

1. Easy for the people creating documentation to learn
2. Easy for them to complete everytime we have an upgrade or change
3. Ability to ship a easy to use online help file with the product
4. Ability to print for the hard copy people, without needing to keep multiple versions
5. Ability to have context sensitive help based on the screen the user is viewing within the product.

As I mentioned we currently use MS Word, given most users are Windows based I began looking at HTML Help 1.4. My first thought is either I am lacking brain cells today or the documentation/help for the product is not up to scratch. (This is quite ironic given the product.) So I began to convert our MS Word files into HTML using the "Save As Web Page" option thinking that Bill's organisation would have these things nicely integrated. This was my first mistake:-

• The Word specific XML tags placed around image result in the file not being understood by the HTML Help product. Given the document is full of images not a good start.
• When allowing HTML Help Workshop to automatically create my contents page, it correctly identified H1, H2 and H3 tags as section headers, but seems to be unable to then create links to these sections. The result a really good contents listing that does nothing.

After several searches on Google I found a tool from Microsoft to remove the additional tags, an surprise my images appeared. Now why did they just not put that feature into the HTML Help Workshop? This got part of my issue resolved, however when printing to PDF from the resulting HTML help file my images disappear AGAIN! Maybe more tweaking will get them back.

This still did not get my table of contents working. I am now starting to feel that we might have to redo our documentation. Now I am looking at a tool called WebWorks Publisher Professional from WebWorks this seems to do everything I need, for US$1000. I have just downloaded the 50MB product, got my evaluation key and off to test. I will update on my results.

I would have thought this would have been easier, I guess I am wrong.

---