Hide full article
Back in 1998, I wrote a TidBITS article entitled "The Death of Documentation," which laid out the reasons why manuals, even those for large and complex programs, had become so small and unhelpful. Six years have passed, and frankly, nothing has really improved. So earlier this year, I came up with an idea for solving at least a portion of the software manual problem that leverages everything we've learned from our Take Control project.
<http://db.tidbits.com/article/04865>
You see, there isn't all that much difference between one of our Take Control ebooks and a manual. Our ebooks tend to be more focused on specific tasks, and don't attempt to cover an entire program, but the problems we've solved, such as how to produce professional content presented in an extremely readable PDF-based layout, are identical to those faced by developers looking to create a manual. "So," I thought, "why don't we just write the manuals for appropriate programs?" In considering how to answer my own question, I realized the key lay in figuring out how an author writing a Take Control manual would be paid for his or her effort.
Knowing the kind of sales figures we had for Take Control titles on extremely common programs like Microsoft Entourage 2004, Word 2004, and GarageBand, not to mention Mac OS X 10.3 Panther, it was clear that independent titles covering less-common applications simply couldn't generate enough sales to be worth the effort. Even if thousands of people purchase a given application, the percentage that would buy a separate (and potentially competing) manual for the product won't be all that high. Besides, manuals should come with the associated program; it feels wrong somehow to charge users for the documentation necessary to go beyond the visible interface. The solution soon became obvious: negotiate with a developer to write a Take Control manual that would be bundled with the product in exchange for a per-unit royalty. The developer could then decide how to handle the royalty, either taking less profit at the same price point or raising the price to offset the cost of the manual.
Of course, this strategy works only if the product sells in sufficient quantities for the total royalty to make the author's time worthwhile; I suspect that with a $5 royalty matching a roughly 50-page manual, for instance, a product would have to sell at least a few thousand copies, although all those numbers could be tweaked to make the final recompense worthwhile.
Enter iKey 2 -- It was a nice theory, but the next trick was finding the right program, one that was sufficiently complex and powerful to warrant a real manual, that was in the appropriate stage of development, and that had enough users to make the numbers work out. Plus, since I wanted to write this first Take Control manual myself rather than throw another author into the deep end, it would be best if it were a program I would use in my day-to-day work. Coincidentally, a good candidate appeared quickly. When we were in Hawaii for my sister's wedding in April, we met with Julian Miller of Script Software, and after I told him about the idea, he suggested we work together on iKey 2, a major revision of their automation utility that was in the works.
On the face of it, iKey 2 was the perfect first case, since I was using the 1.0 version, it was already popular, the upgrade was sufficiently major that a large number of upgrades were likely, and it was in a relatively early stage of development at that time. We figured out the details, and I started in on designing a manual and documenting the beta of iKey 2. Six months later, developer Philippe Hupe had a finished version of iKey, and I had a complete 148-page manual. For those who aren't familiar with iKey, I'll describe it shortly, but needless to say, everyone is welcome to download and study the complete manual as a way of acquiring a feel for what iKey can do.
<http://www.tidbits.com/takecontrol/samples/ TCoiKey2-1.0.1.pdf>
Six months may seem like a long time to write a manual, and it felt like it then, too. Some of the delay was my fault, since big projects are difficult for me to fit into my overloaded schedule as it is. Plus, I didn't realize when I started just how deep and powerful iKey 2 would be, since iKey 1 was a relatively simple application. That added complexity was how I ended up with a 148-page manual.
There were also unanticipated challenges along the way. Since iKey 2 was in development, there were bugs to identify, report, and retest in the next version. Although I hadn't signed up to be a tester, it made no sense for me to ignore bugs I found - I wanted iKey to work as well as possible, and I certainly didn't want to document bugs that Philippe could fix easily. Although the basic interface was more or less done, changes were necessary in some areas that I found difficult to document; after all, if it's hard to explain how to use an interface, it's probably hard to use it. And lastly, Philippe is both French and a programmer, which meant that I couldn't resist making suggestions about how to improve bits of text within the interface for English language clarity. All these issues made coordination tricky, since I couldn't document a part of the program until it was finalized, and I couldn't take screenshots until the interface text had undergone an edit pass. There was much back-and-forth, with Philippe being extremely gracious about my suggestions and edits. As it turned out, I ended up doing a lot of work just so I could get to the point of writing the manual I wanted to write. But the result was a program that improved greatly during its pre-release phase.
About iKey 2 -- For those who haven't seen it before, iKey is an automation utility, or what others might call a macro utility. No matter what you call it, such a utility helps you create shortcuts that automate repetitive tasks, much like QuicKeys from CE Software and Keyboard Maestro, now owned by Stairways Software. QuicKeys was one of the first Macintosh programs I ever bought, back in 1989, and I've relied on an automation utility ever since. With Mac OS X, I went through a period of using QuicKeys on my desktop Mac and Keyboard Maestro on my PowerBook, but when Panther came out, I standardized on iKey on both machines for compatibility and synchronization reasons. I won't attempt to compare the three, partly since I haven't used recent versions of either QuicKeys or Keyboard Maestro, but mostly because it wouldn't be appropriate given my experience with iKey.
<http://scriptsoftware.com/ikey/>
<http://www.cesoft.com/products/qkx.html>
<http://www.keyboardmaestro.com/main/>
The two most common types of shortcuts that an automation utility enables for me are switching to specific applications when I press particular function keys and typing various bits of boilerplate text when I press an associated hotkey (you don't really think I actually type "cheers... -Adam" at the end of every email message, do you?). Those are simple actions, but iKey performs other tasks for me that are a bit more complex. For instance, my new method of handling email in Eudora involves using a saved search rather than the In box, so I've used iKey to remap Command-1 such that it opens my saved search instead of my In box. iKey lets me change the functionality of the hotkey without changing the way I work. Things get interesting when you want to string together a variety of actions, complete with pauses or multiple iterations, to automate more complex repetitive tasks. iKey is good at automating complex actions, since it has over 100 individual commands that you can build into shortcuts. So, for instance, I've written a shortcut that creates a properly formatted HREF tag using the selected text as the target and a URL in the clipboard as the destination. That shortcut was tricky (iKey doesn't attempt to provide full-fledged programming constructs, though it can of course execute AppleScript scripts and is itself scriptable), but I use it a lot to write HTML snippets in any program before posting on ExtraBITS or Web-based discussion areas that allow HTML.
iKey shortcuts can be invoked in ways other than hotkeys, too. You can have them trigger automatically at specific times: one of my shortcuts automatically checks a number of Web sites in OmniWeb and Safari every morning at 9:00 AM. Shortcuts can also go off when applications launch or quit, or are activated or deactivated. Then there are system event triggers, for activating shortcuts at sleep, wake, restart, or shutdown. And if you prefer a visual interface, you can create palettes and menus (either normal menus tied to the menu bar or pop-up menus that appear at the pointer location) that let you click buttons or choose menu items to invoke the associated shortcuts.
Since every shortcut, menu, or palette can have a context - an application in which it appears - you can easily make application-specific shortcuts that don't get in the way except when you're in that application. I have a palette, for instance, populated with buttons that type common Unix commands that I've set to appear only when I'm in the Terminal. As soon as I switch to another application, the palette disappears. And the Command-1 remapping I mentioned earlier works only in Eudora, since it makes no sense in any other application.
The possibilities abound with automation utilities like iKey, and the trick is to see when you're performing the same task repeatedly, since almost any repetitive task can have a shortcut. I have a menu that lets me switch my network connections between my two Internet connections without opening the Network preference pane. I also have a handful of shortcuts that let me play and pause iTunes from the keyboard, rate songs, and move on to the next song if shuffle has picked one I don't want to hear. Some shortcuts I use for a few days and then delete, such as one that sped up changing certain settings for many Web pages in Web Crossing's Web-based interface, and others I may use only infrequently, such as one that helps me find bouncing email addresses in a text file of bounced mail and remove those addresses from an address list in another program. It's not something I do often, but it's so numbingly rote that it cries out for automation.
I won't pretend that iKey - or any automation utility - is right for everyone. You have to be able to identify a repetitive action and be annoyed by the amount of time you're wasting while performing it. Some people simply don't feel the brunt of repetition, or the few things that bother them can be worked around in different ways or with different utilities. I far prefer switching to Eudora with the keyboard by pressing F3 than by Command-Tabbing through launched applications, and typing "cheers... -Adam" would get old fast with the amount of mail I send (and no, it doesn't work to put that string in my signature; I've tried it and it often ends up looking strange). But if you do feel a niggling annoyance that the Mac should be able to make life easier for you by handling these various repetitive actions that occur, it's absolutely worth a look at iKey. It's $30 ($10 for upgrades from 1.x), and you can try it for 30 days for free. iKey 2 requires Mac OS X 10.2 or later and is a 2.8 MB download (much of which is my manual, in fact).
<http://www.scriptsoftware.com/ikey/ikey2.sitx>
The Future of Take Control Manuals -- Obviously, I don't yet know how financially worthwhile the amount of effort I put into iKey will turn out to be. However, there's no denying the good feeling of having helped make an already useful program even better, and knowing that users will be able to do more with the program thanks to my documentation efforts. I learned a lot about the process, and although we'll be proceeding cautiously with future Take Control manuals, I think it's going to be one of those win-win-win situations where developers gain professional manuals for their products, users benefit from improved documentation, and skilled authors find a financially viable outlet for their efforts.
