Before I get into talking about Microsoft HTML Help or any alternatives, let me ask you something. ?Have you ever had the singularly frustrating experience of staring blankly at the Google homepage? ?You’re staring blankly because it occurs to you that you don’t even know what words to type.
Maybe this happens because you’re searching for a name that muddies the waters. ?Someone creates a new JavaScript framework named Taylor Swift. ?Or perhaps it happens because you know only vaguely how to describe the concept. ?Try buying a replacement cotter pin?if you don’t actually know the name of the thing. ?You start googling things like “that thing that stops a trailer hitch from falling off my car.” ?And of course, that doesn’t work. ?So you stare blankly, frustrated.
Microsoft HTML Help…or Whatever
Microsoft HTML Help is one of those hard-to-google things, based on my observations. ?Or should I call it Microsoft Help? ?Or maybe “that thing when you hit F1 in Windows and a window pops up”? ?You get the idea.
I’ve seen people to struggle when it comes to articulating this concept. ?Beyond the word “help,” which resides at the center, the rest is a little mysterious. ?And by and large, the world doesn’t care to name it. ?They hit F1 or click for help, and, voil?, help appears in the form of a window. ?What’s to search?
But if you’re making a software product, you might think, “Hey, I want to make a ‘help’!” ?That’s when you’re going to start googling, and that’s when things get weird.
Let’s say you google “create a windows help.”? You get an ad that you obviously skip, and then you have something about creating a help “project” and something about Microsoft HTML Help. ?But you don’t want to create a project or HTML — you want to create a Windows help thingy. ?The next link, “Create a Help Project (Windows),” sounds promising. ?But alas, it just describes things in vague terms, including “create a help project” as well as compiling and testing help…or something.
Ugh. ?This search and others like it invite frantic and frustrated clicking. ?And they do this because sources speaking to the problem assume that you already know how this help thing works.
How This Help Thing Actually Works
So, let’s address that. ?How does this help thing that you’ve seen but never produced actually work?
Well, first, you may need to adjust your mental model a bit. ?There’s a decent chance you might have conceived of it as text, a web page, or maybe the product of a tool reminiscent of Microsoft Project or Visio. ?But it’s not any of those things.
Instead, the generation of this help documentation actually works more like a parallel software development project. ?Think of how Visual Studio works. ?You have solutions/projects, and you compile those into an executable or library. ?That’s a better mental model for Microsoft help file generation.
Indeed, you have to create an actual help project. ?You’ll compile that project using a help compiler. ?And your equivalent of Visual Studio in all of this? ?It’s something called Microsoft HTML Help workshop. ?It will compile your help project, turning it into an output of HTML or the Compiled HTML (.CHM) file that accompanies many desktop applications.
Using Microsoft HTML Workshop
If you go download that thing, you’re in for a sort of rude awakening. ?It works, and it will get the job done. ?But it’s the best of what 1999 has to offer. ?Here’s a screenshot, if you don’t believe me.
If you’ve been around the industry a long time, this battleship-gray, Winforms-style application will seem familiar, if antiquated. ?If you’re newer to the industry, you might think you’ve stumbled into a “History of Computer Science” museum. ?And yet, this is essentially the default mechanism for generating help files. ?And I’m not just talking about the kind that accompany desktop apps — we’re talking about HTML documentation as well.
You’ve Got To Be Kidding Me, Right?
Let me start by framing the discussion a bit. ?As archaic as this may seem, I’ll say something that I often say about legacy apps and code in my travels. ?It may inspire disbelief, but you also have to summon some respect for it. ?How much code that you wrote 20 years ago is still getting the job done in production? ?That’s no small feat. ?The fact that something written during the Bill Clinton presidency can still generate a rich help utility for you is impressive.
That said, I understand your reluctance to use it. ?And in fact, others share this reluctance. ?Here’s someone wondering if this thing can even work on Windows 10. ?People want to generate HTML and CHM documentation, but they wonder if some other tool can help with this.
Alternatives to Microsoft HTML Help via HTML Workshop
The answer is, of course, yes. ?It wasn’t lost on the broader developer world that people might want an alternative, nor was it lost that this might integrate nicely with other products. ?And so over the years, people have indeed developed alternatives.
But of course, with options comes confusion. ?Are you looking to generate end user documentation, or are you looking to document an API? ?Where and how will you distribute the help, and via what medium? ?Plus, if you go looking through old Stack Overflow threads, you’ll find that some formerly lauded alternatives have become defunct.
Some tools have stood the test of time. ?GhostDoc (Pro), for instance, scratches the itch of generating documentation about your code.? GhostDoc helps you manage XML doc code comments as a primary feature, making it an ideal candidate to give you a head start in generating CHM files. ?Just take the comments you use for maintenance and IntelliSense, and automatically turn them into a distributable help file. ?You never have to worry about using Microsoft HTML Help, nor do you need to give much thought to the input formats or generation (“compiling”) of the output.
Make Sure You Upgrade Your Experience
GhostDoc isn’t the only option that you have when it comes to generating help output. ?Maybe you fancy a different tool for a different integration or set of use cases. ?You’ll have to download and try out tools to identify the best option for you.
But whichever one you use, I strongly recommend that you choose one of them besides Microsoft HTML Help, if possible. ?I really don’t aim to knock that tool, but it’s sunset and pushing 20 years since it’s had an update or patch. ?The output file formats live on and are still going strong, but you don’t really want to count on a sunset technology.
Hopefully you now have a better understanding of how the whole help file thing works. ?And hopefully you won’t stare in frustration at Google, looking to understand exactly what you need. ?All you need is understand Microsoft HTML Help and then pick an upgrade over it to help you.
Learn how GhostDoc can help to simplify your XML Comments, produce and maintain quality help documentation.
