Fog Creek Software
Discussion Board




Creating help files from Word documents

In previous versions of our programs, we used DocToHelp to convert the Word document (manual) into Help files. It worked, but with lots of fussing and frequent crashing. It got the job done, but left me resolved to do it differently next time. It was particularly annoying that the company had lousy manuals (good for getting started, but nothing for troubleshooting), little tech support on the web, and then charged for email or phone support.

DocToHelp gone through a a few new versions since I last used it, and has been sold to a new company. RoboHelp also seems to have evolved a lot.

Anyone have any experiences, good or bad, with DocToHelp or RoboHelp or others??

I should mention that we are converting large manuals (200 pages and 500 pages) to help files.

Harvey Motulsky
Tuesday, June 04, 2002

Harvey,

Our company also started out with DocToHelp and then moved to RoboHelp when we became too frustratred.

The problem with RoboHelp is that it is a help development environment, not a converter. Creating a help file from a Word document is not an automatic process. In order to preserve the work done when a Word document is converted, our technical writer ended up editing both the manual and the online help whenever there was a change. When this became too costly, I decided to reevaluate the available products.

The most recent version of DocToHelp is an improvement. However, it was not sufficient for us to give up RoboHelp.

The most recent version of RoboHelp Office 2002 is quite good at converting Word files to HTML help. However, you will still have some work to do in order to remove some orphan pages and set up the page navigation order.

In the future I intend to work only with Word files and convert them to help as automatically as possible. I have performed some successful tests with a manual of approximately 100 pages containing text and screen captures. To get a good looking result, I did have to put some effort in creating a Word style sheet that gave me the correct look for the help file.

Good luck.

Jacques Benoit
Tuesday, June 04, 2002

If you haven't already got everything in a Word document, consider using Doxygen [ http://www.doxygen.org ] - it will provide you with many useful output formats, including rtf, latex, html and - of course -  indexed .chm.

Ori Berger
Tuesday, June 04, 2002

Has anyone figured out how to create help files (.chm?) by hand? I am having a rough time finding documentation in the MSDN Library...

I believe I should understand how something works, before I use a tool to automate it.

Daren Thomas
Wednesday, June 05, 2002

Harvey Motulsky wrote:
<<Anyone have any experiences, good or bad, with DocToHelp or RoboHelp or others??>>

Help and Manual seems to be recommended a lot in the Delphi newsgroups:
http://www.helpandmanual.com/

I don't use it because it uses rtf as native format. I prefer to create my HTML help files with an HTML editor and not with a Word type application.

Ori Berger wrote:
<<Has anyone figured out how to create help files (.chm?) by hand?>>

You can do that with the Microsoft HTML Help Workshop:
http://msdn.microsoft.com/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp

The application's GUI belongs in the eternal GUI gallery of shame, but it works. My HTML help pages are created with Dreamweaver and then compiled with the MS HTML Help Workshop. If somebody has a better way, I'm open to suggestions.

Jan Derk
Wednesday, June 05, 2002

I'm also using Dreamweaver and MS HTML Help Workshop. This setup works quite well, but the Help Workshop is one of the most dreadful programs I've ever used. And the HTML Help API isn't so bug-free either, but I can live with it.

One of the keys to be able to create HTML files easily is to have all formatting in an external CSS style sheet, so you don't have to worry about that when you're typing in Dreamweaver. It works best when you override basic HTML tags like <h1>, <p>, and <td>.

Frederik Slijkerman
Wednesday, June 05, 2002

Frederik Slijkerman wrote:
<<One of the keys to be able to create HTML files easily is to have all formatting in an external CSS style sheet , so you don't have to worry about that when you're typing in Dreamweaver. It works best when you override basic HTML tags like <h1>, <p>, and <td>.>>

Gee scary... that's exactly how I do it. Maybe we are both equal geniuses to do it that way. (or equally stupid, of course).

Jan Derk
Wednesday, June 05, 2002

In house we converted our manual from a word document to help pages by writing some VBA macros (Remember it's a near fully featured VB5/6).

Our manual was written using outlining and we had to "hand" code some sections but in general the process took one programmer around a week to do.

This was converting to WinHelp files rather HTMLHelp files but I would guess a two stage DOC->RTF->HTML type process might prove easy enough.

You may well find this a worthwhile exercise for an intern or very junior programmer.

Peter Ibbotson
Wednesday, June 05, 2002

Jan: Maybe we both looked at how the Windows 2000 help files were built. :-)

Frederik Slijkerman
Wednesday, June 05, 2002

Just to be that guy twho throws out the obligatory change what you are doing comment:

Any reason you can't go to straight HTML as opposed to HTML Help?  If you are doing a shrinkwrap destop product, I understand the desire to have Help files available if you are not on the web, but you could still save ethem locally and use the browser to render them.  For anything internet/enterprise based, I would advise putting the help files on the network. 

I'm a developer and I work with many different technologies.  Most of these come with some sort of manual.  I've found that the best way to make my team productive is to put all my documentation on apache in straight HTML format where it is accessable by everyone.  Errata are now easy to publish, and I can add a new technology just be adding the help files along side.  For distribution purposes, you could deliver a self extracing archive that by default is used on the local machine, but could be added to a web server with a minimum of effort.

adam
Wednesday, June 05, 2002

Help and Manual is amazing. It generates HLP and HTML Help files, as well as a properly formatted manual in RTF or PDF formats. It's fast, well written, and works how you'd expect.

Well worth the price of admission.

http://www.helpandmanual.com

Tim Sullivan
Wednesday, June 05, 2002

I was going to mention Help and Manual too.  Works exactly how you expect it to.  However, it doesn't have anything that I know of to convert Word into HTML Help.  I'm not even sure how something like that would work.

Richard Kuo
Wednesday, June 05, 2002

Adam: By compiling your HTML files into a .chm file, they're much easier to access. I think that a table of contents, a  full index, and a search feature are required for good online documentation, and these are difficult to realize if you're only using HTML. Also, a single .chm file is easier to distribute.

Frederik Slijkerman
Wednesday, June 05, 2002

*cough* LaTeX *cough*

Alex Russell
Wednesday, June 05, 2002

I use the template families feature in CityDesk to create two versions of our docs. One version is converted to a compressed help file and ships with the product, and the other ends up on the web site as an on-line version of the help. I only need to maintain one set of docs, customers get a nice help file, and potential customers can see what my products do.
The on-line version of the help for Task Tracker was created in this fashion, at http://www.positive-g.com/tasktracker/docs/index.html

Rik
Monday, June 10, 2002

Frederik Slijkerman wrote:

"Adam: By compiling your HTML files into a .chm file, they're much easier to access. I think that a table of contents, a  full index, and a search feature are required for good online documentation, and these are difficult to realize if you're only using HTML. Also, a single .chm file is easier to distribute"

CHM files are created using Microsoft's proprietary HTML format. They are still HTML files, except that they are compressed. In fact, CHM files, in standalone HTML are much too large, bloated by the nonsense Microsoft pumps into many of it's languages and expects us to deal with.

Anything a Microsoft CHM file can do, A HTML file can do, but it can do it much better and quicker.

As for distribution and compression, there is rar, zip, winace, and many other compression formats to choose from, all of which give better compression ratios and most of which provide functions to distribute and install your help files.

When it comes to creating help files, the last program I would use is Word. It produces too much unnecessary script and does not fully understand HTML and CSS. CSS being of course, the key to a successful and simple way of maintaining and updating HTML documents.

Try using Frontpage or Dreamweaver if you need to use a wysiwyg editor, but frankly, it is much quicker, easier and cheaper to code the HTML and CSS yourself, using a simple editor such as EditPlus, Editpad, or any of the ASCII Editors which provide scripting and coding capabilities. Many of these editors now provide functions far in excess of what Word documents alone can achieve, even if Word is capable of using VBA.

I would advise downloading the HTML and CSS specs from  www.w3c.org . It will open up a whole world of discovery and possibilities.

Try using one of the commercially available CHM creators and take a look at the source code they produce. Anyone can reproduce these documents quickly and simply, since they are only really Microsofts extension of HTML.

HTMLDude
Saturday, March 22, 2003

Just as a note, FrontPage and Word use the same MSHTML engine. So any code created in FrontPage will be almost exactly what Word creates.

Dustin Hansen
Monday, April 14, 2003

Wow! So much information in one spot. It looks like a year since anyone posted here. Has anyone used any of the newer versions of Word (2002 or XP) to try and develop .CHM files? I'm interested in seeing if the XML capabilities in Word are worth dropping money into updating our Office Suite.  I've written a script that cut's word documents by styles and saves them as HTML. Then I run all of them through the MS Filter that takes out all of the extraneous stuff MS put's in the conversion to HTML. I was looking to try and play with the HTMLHelp api with VBA and create the whole file from one macro in Word, have any of you done this yet?

Jonathan M. Maes
Tuesday, March 02, 2004

*  Recent Topics

*  Fog Creek Home