Posted By Paul Kafasis on May 19th, 2006

Over the years, we’ve had many different Help windows. Both the style and the creation method has changed and improved, which makes it fun to look back and see the old versions.

Manual Version 1

First up is Audio Hijack’s help window. Audio Hijack was our first application, and this screenshot is from version 1.6, released in December of 2002. As you can see, there’s not a whole lot to the manual. In fact it consists of just five pages, one per tab. That counts the Glossary, which defined each and every item of the application textually and the License that no one reads. So really, this manual page had a Read Me, and two tutorials, one on the basics of hijacking and one on using timers. Each file was just a small text file (RTF (Rich Text Format), actually), and it was easy to maintain, by simply editing the current version. Overall, this was a very skimpy manual.

Manual Version 2

Next up is a screenshot from Audio Hijack Pro 1.2.6 and you can see we changed the design dramatically. This was necessitated by the addition of many more pages and the switch to simple HTML files. Under the old system this manual would have required ten to fifteen tabs, and that wasn’t going to work. Instead, the contents are embedded on the left side of the manual. There’s a language selector for multiple languages, and a way to save or print the contents seen. We also added more tutorials (for the Pro version), a troubleshooting page, a graphical overview of the application, and other minutia.

Manual Version 3

Here we have the manual from Audio Hijack Pro 1.3.2, the last version in the Audio Hijack Pro 1 family. This change is much smaller, but it was important. We picked up a standard Cocoa toolbar, moving the Print option and Language selector up there. We also moved the contents to their own drawer, which looks and scrolls a lot nicer. One new “feature” was a text size adjuster, which is very handy. This design is quite similar to what is currently in use in all of our applications, as seen…

Manual Version 4

…here, with the Audio Hijack Pro 2.5 manual. This is much more of a “book”, as it has a cover page and very distinct sections. The Table Of Contents also received a nice little black and white graphic to break up the mass of text. Behind the scenes, this version utilizes Apple’s Web Kit to render all the HTML. This has provided both useful and frustrating, as Web Kit has slowly improved. You may notice printing was removed, as it never really worked properly. In it’s place, we offer a PDF download of the manual (linked from the Read Me page) which can be read anywhere, or printed.

That’s where we are right now, and overall we think it’s pretty good. We recently posted the PDF manuals online in our support center and in each product page. However, there are several improvements we’d like to make in the future (beyond the always-desired improved content).

The Future

Many users ask for printing without noticing the PDF download, so enabling easier printing would be good. It’s been suggested that we include the manual externally with the download. However, from day one we’ve always embedded the manual inside the application and have no plans to change this. In this way, the application can be easily installed via drag and drop, and nothing ever gets lost.

Another small improvement is linking directly to sections from inside the application (such as in error dialogs), which can be very beneficial. This requires very specific writing of the various linked pages, as well as changes in the applications, so it’s been slow to occur. Several errors in Nicecast link directly to manual pages, and that’s worked well, so hopefully we’ll do more of this in the future.

How About Search?

Perhaps the single most requested feature that we’ve yet to implement is the ability to search the manual. Few people read the manual, and even fewer read it straight through. We try to write the manuals with this in mind, providing clear sections, tutorials for specific common goals as well as Advanced Topics pages for more obscure tasks. None of that, however, enables the user to say “I wonder what Tags are for”, and then search for that keyword in the manual.

Right now, one can download the PDF copy and search that, but that’s hardly the best we can do. Implementing a search function is one idea, but we’re also considering simply switching the built-in manual to PDF. This simplifies both printing and searching, but it makes things more difficult as far as creation of the manual goes. Right now, the manual is automatically created pulled in from an SVN folder containing HTML and image files, but creating the PDF requires manual interaction. If we can find a good PDF creation method, we’ll likely switch it over and build from there.

So that’s where we’ve been, and some of where we’re going. Hopefully in another few years we can look back at our current design and see many places we’ve improved. Do you have suggestions? Let us know in the Comments section.