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.

(more…)

Though I’ll talk today about .NET code documentation, I want to start further back than that. And by “that,” I mean further back than .NET. I realize that may date me somewhat, but please bear with me.

Most things in the programming world date back further than you’d think. For a dramatic example of this, consider functional programming. All the rage today, it actually dates back to the 60s in practice and 30s in theory. Speculating about the reason for temporal myopia would go beyond the scope of this post, but understand that this tendency toward myopia does exist.

With that in mind, let’s talk about some GUI builders.

A Tale of Two GUI Builders

Now we get to the part that predates .NET. I’m going to reach back into my early career and compare my relatively simultaneous experience with two GUI building technologies.

First, I encountered Swing, a Java GUI toolkit. While Swing did not include a GUI builder at the time, my project packaged it with one. I cannot remember its name for the life of me, but this thing was a train wreck. Moving controls around on a form caused the spewing of improbable amounts of code into my Java classes. Attaching handlers to GUI events only half worked, requiring wire up by hand. I had such struggles with it that I gave up and just hand-coded everything in Java.

Shortly after working on that project, I found myself saddled with a VB6 application. At the time, .NET actually existed, but nobody had ported this thing to it. So I used VB6. And I loved it.

That probably sounds as weird to hear as it feels to type, but there it is. Compared to my experience with Swing and its nightmarish GUI builder, this was a refreshing summer breeze. I could move controls around to my heart’s content, wire up events easily, and get stuff done.

(more…)

More than a decade ago, I worked somewhere that would ship CDs containing commercial software.  Along with others, I’d program applications that ran commercial mail sorting machines and provided a user interface for the operators.  To update or patch the software, we’d cut official CDs and send them out in the mail.

These CDs would, obviously, contain the software.  But they’d also contain a rather elaborate PDF of the user’s manual.  In some cases, we might mail them a physical user’s manual.  And that manual was a formidable, polished document.

You’re probably expecting me to complain about writing that document.  But I won’t do that because I never had a hand in writing it at all.  Back then, we had a professional tech writer on staff that handled all manuals and end user documentation.  At most, I would interact with this person when he’d shoot me the occasional email, asking how something worked.

If you were to ask me about documentation tools back then, I’d have looked at you strangely.  I dunno.  Ask the tech writer.

Documentation Tools Today Run the Gamut

Today we have a much different landscape.  Between the rise of agile methodologies, ease of software delivery, cost savings, and automation, I suspect very few organizations hire tech writers to draw up user manuals for their products.  That’s probably gone the way of the installation CD.

And today you probably have to help out when it comes to documentation.  That means you need to leverage some documentation tools — at least if you want to avoid serious boredom.

Also complicating matters is the fact that modern documentation takes many forms and has many audiences.  Gone are the days of only CD user manuals and man pages.  So I’ll talk today about documentation tools, but I’ll divide the discussion up by audience and purpose.

(more…)