Thursday, 16 November, 2000
The Single Source Documentation Myth
One of my duties at work these days is the documentation for our product. Up to now, I've just been editing the existing documentation and adding new stuff as required. The documentation needs a major overhaul, but that's a huge undertaking. I also need to start on the manual for our latest project. I've been putting it of while I try to find a better documentation tool than RoboHelp, which is great for creating WinHelp or Microsoft HTMLHelp files, but pretty much useless for anything else, in my opinion. Their "portable" HTML Help requires too much from the browser, and single sourcing WinHelp and printed docs creates hideous printed documentation.
I've never seen a good single-source tool. The goals of printed documentation are fundamentally different than those of online docs. Using the same tool to create both kinds of documents usually results in one or the other (sometimes both) being wholly inappropriate.
I've also not yet seen a tool that does a good job of creating help files for multiple platforms. It should be relatively easy to create a good portable online help engine that provides all of the features of Microsoft's WinHelp, but uses something more reasonable than RTF for the input. The WinHelp output file format, too, is way too complex. This would be an excellent Open Source project. If somebody created an open and portable online help system that has most of the features of WinHelp, people would use it. If you added the ability to convert RTF files to the new format, I suspect that people would switch from WinHelp to the new system. Certainly people who are porting Windows applications to Linux would love it. If you know of a good portable format, please let me know.