Technical writing unchained - a custom approach to help authoring

After a decade of writing documentation for high-quality products using robust authoring tools, I've often wondered... what approach would I take if I was doing this just for fun, with no restrictions? What if help authoring was my hobby?

It's a rather insane idea: technical writing as entertainment. But I haven't hit my head, or quaffed one slushy too many (although I've suffered many cases of brain freeze). Remember the personal computer industry 25 years ago? When computer users were geeky college kids who spent three hours typing in machine language to make a ball bounce across the screen? It was about fun. And where do you think all of those Unix MAN pages came from? Hobby computer geeks writing for the sheer fun and glory.

So, let's say I'm building a help project for fun. How would I equip myself?

Right off the bat, I'd throw out my HAT. (Sorry, the rhyme was completely unplanned.) Not because they are bad; in fact, robust tools are essential for multi-author environments where efficiency is key. But if I'm doing this on my own, I don't need the headaches that come with an integrated tool set, nor could I justify the expense. (It isn't that fun of a hobby.)

Why choose small tools? Big programs tend to crash more. (That's a generalization, but a good one, I think.) Small, specialized programs would allow me to author my help project without the hassles caused by all-in-one solutions. And I can get the tools for free.

All output features, such as navigation, I'd build myself.

My project would consist of a well-structured set of folders, similar to the output you get when you generate browser-based help.

I'd start by installing Notepad++, including a spellchecker plugin. Seriously, if I'm going freestyle, all I need are line numbers. Bells and whistles, drag-and-drop, and WYSIWYG tools are great if you're drinking the HAT kool-aid, but I've always preferred working under the hood. (Maybe that's why my help authoring tools crash often. You can't hot-rod them the way you can a 1970 Chevrolet and expect everything to run smoothly. I've tried, with only limited success. You can't just "bolt on" some extra subroutines.)

Next, I'd install Perl. Perl is like a Swiss army knife; when you need a can opener, it can get you pretty close. I'd use Perl for global search and replace, reporting, and for auto-generating navigation components, which I'll talk about in a bit.

Last of all, I'd install a link checker. Xenu's Link Sleuth is good, and produces very thorough results.

Now the fun begins. After editing my topics in Notepad++, I'd run a home-brew Perl script to auto-generate a collapsible table of contents based on topic titles. A meta-data tag embedded in each topic would tell the script whether to include a topic, and where to put it.

I'd hard-code my index, or build it from meta-data tags, but with careful planning and selection. There's no better way to do it. An index needs to be created manually in order to be really useful. Readers don't think like computers.

Here's where it gets interesting: Search functionality.

For search, I'd install the Google Adsense search tool. Why? Because nobody knows search better than Google, and their algorithm is incredibly advanced. It's like tapping your help project into HAL 9000 or something. People will find what they are looking for.

Also, this is a hobby project, so why not make some money from it to fund future projects? Awesome search plus free cash? I'm sold.

For analytics, I'd do the same. Google Analytics would let me fine-tune my keyword usage based on actual search behavior. That way I can optimize the findability of my help topics. Also, the bounce rate would tell me whether my content is really addressing the needs of users. (This can get tricky. See this post on using analytics for documentation for details.)

Last of all, for quick-and-easy compilation, I'd daisy-chain all of the Perl scripts into a Windows shell script or BAT file so I can build the whole kaboodle with a simple command.

That's it. That's how I'd build a home-made system for authoring help.

Maybe one day, in my vast amounts of free time, I'll give it a whirl on an open-source project. But I'm guessing others have blazed this trail already and still have the results archived on a floppy disk somewhere. If that's you, I tip my hat in your general direction.