A recent mailing-list discussion has raised my hackles about documentation. So at the risk of offending all the tech-writers out there, let me restate my thesis: Documentation Sucks!

I’m not just saying that because I’ve been very slow to provide substantial documentation for my two in-house applications. The only thing worse than lack of documentation is too much documentation. It’s too often a sign of design failure in the application. Documentation is insidious. As soon as it reaches a certain size, it seems to become a black hole for “explaining away mistakes.” The new feature is completely unintuitive, but completed by the deadline? It’s OK, just stick a note in the documentation! Then you end up with a big junky piece of unusable music composition software, or ridiculously ill-behaved spreadsheet app.

When you install a piece of software, its value can often be measured by how much you can get done without looking at the manual. I’m not saying there shouldn’t be a manual (except in rare cases), but it shouldn’t be necessary for your first conversation with the program.

Who here has read the manual for Safari? The Dock? Address Book? You haven’t? How do you get anything done?! Do they even have documentation? Sure they do, but they’re not mammoth, and they’re mostly there to feed the public’s addiction to documentation. Take Address Book. If you open its help book from the Help menu, you’ll see the the documentation is split up into four fairly discrete sections:

The first section is sort of a “release notes” for consumers. This is valuable, but hardly needs to be in the manual. In fact, it’s probably the last place I’d look for it. For a paid product, I would expect to see it on the web in marketing information. This is the type of information that Apple gets to include in the documentation because they push their applications to us for free. We don’t have to decide that there is a true benefit to us before deciding to upgrade to them. So they have to sell us on the application after we already have it!

The second section is also essentially marketing information, but packaged as a “getting to know your new Address Book” type section. There is some helpful stuff in here if you’re looking to do advanced features like syncing, but in the “obligatory documentation” department we get items like this:

“Oh that’s what the little oval box with the magnifying glass in it does!” Don’t get me wrong, users need to know this! But if every application takes responsibility for explaining every UI convention to every user, there will be a whole lot of reading and whole little of doing.

The third section: “Solving Problems” is really the holy grail for users. It’s both the only section users really need, and the only section that can’t be written without their help. Until your users present problems, you can’t succinctly elaborate on them in the documentation. This section, in addition to being the only useful one, is the one that you want to focus on eliminating as revisions to your application are produced. Your bug list and your “Solving Problems” list should be pretty well in sync.

When’s the last time you needed a manual to watch a DVD? Is there a manual? There’s a complicated (sometimes infuriating) user interface that provides access to a sometimes large number of features. The UI is in fact much less standardized than a typical computer UI. Yet there’s no manual. Why? Because the penalty for making a mistake is small and the consequences of an action are clearly communicated to the user. The only thing you need a manual for on most DVDs is to find the secret, hidden “easter egg” features. Unfortunately, many applications on the Mac treat all features like easter eggs. Want to copy text from one paragraph to another? “First, go to page 182.B of the manual. Now, while pressing control, shift, and caps-lock, turn around 3 times while fingerspelling ‘Paperclip’ with your free hand. To learn more, please turn the page.”

For that matter, when’s the last time you read a manual for a hammer? Pair of pliers? Your desk? The rug on the floor? For which tools in your life do you find high value in the manual? Is it valuable because it’s required to use the product or because it enhances the product? If it’s required then don’t you resent the manufacturer?

A great example of an extremely complicated, extremely dangerous application with a minimalist manual is the automobile. Most of us trust ourselves implicitly to step into any automobile manufactured in the past 60 years and get from point A to point B with relative ease and absolute safety. Sure, there’s a manual for your car, but have you ever looked at it? I’ll tell you what it says. It has some ridiculous stuff like “This is a key. Keys make your car start. Please don’t pump the gas while the car starts.” OK, that’s filler, but the manual is still thinner than most software manuals. If you’re lucky, it also has some really useful Solving Problems stuff like “Oh Crap. Your battery’s dead. You probably thought you’d never have to do this, but here is how you jumpstart a car.” (Some automobile manufacturers, realizing that the Solving Problems list is also a bug list, have added features to their cars like backup batteries to automatically jump start the main battery when it dies. Nice!)

Nowhere in your car’s manual does it say “vehicles approaching at 60MPH should not be collided with head-on.” We are “car literate,” so we know these things without having to be told. In fact most of what we know about driving and cars we learn by observation and experience – we are exposed to driving from a young age and become confident about our understanding of the complex system. Sure there is training, but once you learn how to use one car, you are in a good position to use any car – and most importantly, these pre-requisites are not the car manufacturer’s responsibility! This is how computer software should be. Customers who are minimally computer literate should be as comfortable stepping into your software’s trial period as they are stepping into a rental car. As our world becomes more and more computer literate, it’s becoming an insult to explain things like “This is a search box. Search boxes are for searching.”

Car companies save a lot of paper because there isn’t an expectation of a phone-book sized manual when you buy a new vehicle. The software industry isn’t so lucky. One of the biggest ways in which documentation sucks is that parts of the computer-using masses (particularly those who still feel a bit cautious about getting behind the mouse) have been conditioned to expect manuals for everything. And big manuals, at that! If we don’t get a big manual from the manufacturer, we’ll pay some book publisher for a big fatty.

Two decades of crappy software and obligatory documentation have conditioned users to expect the worst. We need to wean the world off of manuals by proving to them that we too can get them from point A to point B without getting injured.

It looks like my dreams of replacing my Dell with a new MacBook are (temporarily?) shattered. [Via DaringFireball.net]

Now that Apple has announced the immediate availability of Intel-based Macintoshes, the developer community needs to get serious about adjusting our projects so that they build and run natively on the machines.

For a long time, Apple has made available the required SDK for “dry running” our projects as Intel-compatible builds. Some developers even took Apple up on the “transition kit” systems, which put Intel machines (though quite unlike the shipping units) in the hands of developers from a very early stage.

A common thread on the mailing lists seems to be the unhappy scenario of essentially having ones own code ported and ready to test, but being held hostage by the slowness of another library upon which you depend. When the library is open source, it’s easy enough to take responsibility for it yourself. Get your feet dirty and port the dang CurlHandle class over yourself! But many of us (perhaps unwisely) have gotten ourselves into situations where we depend upon the compiled code of others in our shipping products.

Kagi’s KRM module allows Kagi vendors to present users with an integrated purchasing dialog. It’s essentially a single dialog that takes the user’s financial information and ships it off to a Kagi server for further processing.

For those of us who have been using the Cocoa-specific version of KRM, the wait has been long for a universal version of the libraries. In fact, the wait will be very long. It doesn’t appear that Kagi is planning any further updates to the Cocoa-specific module. Instead, we’re offered the “Zonic KRM” module, which is a straight-C CarbonEvent based solution.

At first, I was annoyed by the presumption that Cocoa developers should have to pull up roots and switch to a new library with a new API (a straight-C one, to boot!). But after downloading and using the Zonic KRM solution, I am happy to report that it’s an overall cleaner and easier to use module than the previous Cocoa-based framework. As a single library archive and associated header file, this requires none of the linking and packaging headaches of the Cocoa KRM package. The API is straightforward and offers few opportunities for careless error. Even the UI is, ironically enough, improved over the Cocoa version.

The only major snag I’ve run into is that the Zonic purchase window doesn’t appear in the floating layer as the old Cocoa KRM did, and seems to suffer some activation issues when invoked from my LSUIElement application. These types of problems were what originally led me to choose Kagi over eSellerate, whose Carbon-based solution had the same problems. Hopefully these can be resolved with Kagi – I’ll have to investigate. [Ed. Note: These issues were more or less mistaken impressions, and are somewhat elaborated upon in updates at the end of this article]

All the improvements will mean little, however, to Carbophobic developers who have grown accustomed to avoiding most APIs that don’t fall firmly into the Cocoa space. I don’t blame them. If I didn’t already know this Carbon stuff, I probably wouldn’t want to sidetrack my rapidly progressing project to figure it out, either.

In the spirit of helping these developers out, and with the somewhat selfish goal of encouraging as many Intel-native apps as possible by the time my MacBook arrives, I’m posting a very simple demo project that shows how you might integrate the Zonic KRM modules into a Cocoa application. For this example, I’ve taken the attitude that you want your exposure to Carbon to be brief, handing back control to a “sane, Cocoa world” as soon as possible. The gist is pretty simple:

1. User pushes a button, invoking an IBAction method.
2. Action method installs a Carbon event handler for Zonic “I’m Done.”
3. Action starts a modeless Zonic registration dialog.
4. Zonic finishes and issues the Carbon Event.
5. Callback receives event and passes event-completion structure back to Cocoa.

[Ed. Note: It has been pointed out that using the “modal” Zonic dialog is exceedingly simple, and doesn’t require any use of the Carbon event API.]

Note that since I’m not sure I have the right to redistribute the Zonic library and header file as-is, I’m not including them in the sample project. You’ll have to download them directly from Kagi.

I hope this proves helpful to some of you.

Update – My LSUIElement problems seem to be worked around by using the modal version of the Zonic dialog API.

Update 2 – Wed, 1/11/2006, 1:40PM EST. I’ve updated the sample project to include demo cases for both Modal and Modeless variants of the Zonic KRM dialog.

Update 3 – Wed, 1/11/2006, 1:55PM EST. Another update to the sample – should dispose of the Zonic result structure when done with it. Also, it should be noted that the “LSUIElement” related problems alluded to above are more general. It appears that Zonic KRM’s modeless dialog is not well suited to being displayed while a Cocoa NSPanel of any kind is being displayed.

Update 4 – Thursday, 1/12/2006, 1:55PM EST. Incorporate memory leak fix suggested by Kirk in the comments.

Update 5 – Friday, 1/13/2006, 10:48AM EST. Friday the 13th Special! Kagi and Zonic have kindly agreed to let me include the Zonic library and header file in the demo project, so it should be buildable as soon as you download it, presuming you have Xcode 2.2 installed.

Update 6 – Tuesday, 2/21/2006. I meant to point this out earlier, but forgot. There is a problem in the 1.0.4 Zonic release that causes it to crash on 10.2 deployments. An ingenious workaround was discovered by another Mac developer and shared with me via Kagi. Simply lipo the PowerPC code from Zonic 1.0.3 with the Intel code from 1.0.4. I’m using this solution in the interim and it gives a solid fix to the problem the Zonic 1.0.5 release is ready.

The other day as I walked home from the gym, listening to my iPod Nano, I started to feel jealous of the iPod Video owners. I love my Nano, but it would be cool to be able to watch video on it from time to time. In spite of having a pretty good color screen, I have no access to such a feature (except perhaps with some Linux-on-iPod trick).

Then I got a sick idea. What if I could convert the frames of a video into chapter markers in an iTunes AAC file?

You may be familiar with chapter markers: they allow authors of multi-part AAC audio files to put marker points in the file so that you can skip between different sections of the audio, even though it’s all part of one file. When you play a song or audio file on your iPod that includes these chapter markers, you can also see an associated image for each chapter.

So, I set out to create an AAC file with lots of chapters. Of course the mechanics of this are a bit harder than it sounds. I had to master Apple’s weird “ChapterTool” (the only official Apple software I know of distributed through a .Mac homepage!), came up with a funny perl script to generate the XML input file that ChapterTool requires, and relied heavily on a modified version of David Van Brink’s qt_tools and Pixture Studio’s awesome QuickImageCM.

I hacked on this for several hours today and finally came up with a pretty interesting demo (10MB). The linked file contains a 3.5 minute song with 800+ chapter markers. The result, as viewed in iTunes, is “somewhat video-like!™” I can’t figure out yet whether the slight jerkiness is because iTunes is not used to flipping chapter art so frequently, or because I screwed something up in the time code generation for the XML file.

Though the file behaves fairly well in iTunes, all hell breaks loose when I try to play the file on my Nano. The Nano sort of freezes for a minute before giving up and skipping to the next track. I guess Nano just isn’t ready to deal with that many chapters in a song file! I tried scaling back my experiment quite a bit by reducing the number of chapters to just one per second. While Nano is now able to play the song, it is rather flaky about keeping the displayed image up to date with the chapters as they fly by. Another major drawback to this “solution” is that having all those chapters on the song essentially makes it impossible to skip to the end or beginning of the track while it’s playing.

So while my dream of hacking video onto my Nano via iTunes is not exactly fulfilled, I think too much went into this not to share the (probably good) news of my failure.