On the morning of January 10, I woke up expecting to waste a couple hours of my day scouring web sites and IRC channels for the latest transcriptions of Steve Jobs’ Macworld keynote speech. It didn’t really bother me that it was not being streamed live this year, because every other year when they’ve tried that, I’ve ended up squinting at a low-quality, slow-updating video and not really getting much more than I would have from the painstakingly verbatim notes I read live on IRC.

While I was expecting to throw away a couple hours, I didn’t yet know I’d be throwing away a couple thousand dollars. [“Throwing away” will seem less appropriate once I actually get the hardware!] I knew I needed/wanted to get an Intel box sometime soon, in order to start testing my own software. I’d made whatever “transition” was necessary in theory months ago, but in practice I’d yet to try the apps out in a live Intel box.

So when I saw the Intel iMac, I sighed. No Intel for me, I thought. I had subconsciously formulated an Intel fantasy that involved buying an Intel-based Mini, using it in the common area as a media center, and rebooting it into Windows XP as necessary for my work. I already use VPN for almost all of my PC needs. The ugly Dell sits underneath my desk, serving mostly as a foot warmer and sometimes as a reminder of just how good we have in the Mac world.

When the MacBook Pro was announced, however, my ears perked up. My “portability” currently consists of a 500MHz iBook G4, stuck on 10.3 because I’ve been too lazy to figure out how to install Tiger from a hard drive (no DVD drive). This announcement gelled for me a magic combination of want and need. I need an Intel machine to test against. I want a laptop to cruise to the cafe with. OK, sold! I placed my order at 11:08AM PST. The problem is, it’s not slated to ship until February.

I’m getting impatient! Other people are getting iMacs, and I’m stuck on the waiting list. I’m considering switching my order to an iMac – perhaps I can replace my Dual G5 2.0GHz with… an iMac? If there was ever a good time to sell a powerful G5, it’s probably now. While the G5 still runs Photoshop faster than an Intel-based Mac.

I got so impatient to try out my in-house applications, that I built Universal copies and posted them in a private section of my web site. I then went to my local Apple Store (after calling ahead to confirm that they got their Intel macs on schedule) to do a little test-drive.

I walked into the Apple Store and started scanning for the word “Intel.” Nowhere to be found. There were tons of iMac G5 displays, but no Intel iMac! Damn it! They lied to me. As a last stab at success, I asked an employee, “Are there are any Intel iMacs on display?” I tried to feign consumerism so he wouldn’t get suspicious about my motives. “Sure, we have one right over here. There isn’t much on it, but you can surf the web or whatever.” Something tells me Apple wouldn’t be too happy to have their employees describe the “full suite of Apple applications” as “nothing much.”

The machine he escorted to me was indeed Intel-based, despite the outdated “iMac G5 – $1299” placard next to it. I guess a side-effect of not changing the price is that it allows retail stores to be lazy. I went straight to my web page, downloaded my universal apps, and attempted to launch them from the Desktop. “You are not allowed to launch this application.” What! Oh crap, I’m going to have to come clean about my motives. I thought there was like a 10% chance the Apple store employees would take pity or be awed by my plight, and let me loose on the machine. But the 90% chance of them just saying “No” and then watching me more carefully informed my decision to just play around a bit.

In a short while I figured out how to work around the security. And that made me feel pretty bad-ass. I’ve got code to debug, damn it! I excitedly launched my applications, only to learn that they were in fact not Intel compatible. I was really expecting them to launch and run without a hitch. “Well, better to find out now than to ship and let my customers find out!” I rationalized. But I was a bit bummed. I basically do things “by the book.” Why don’t my apps run? In fact, one runs and one crashes. But the root cause appears to be the same. I’m getting some kind of NSUnarchiver based exception. Does this look familiar to anybody?

It’s hard to debug the problem at the Apple store, since they don’t have Developer Tools installed. So I took some notes and scp’d them up to my web server from the store. When I got home I examined the logs (and a stack trace in the crasher case) more carefully.

I’m assuming there’s some data somewhere that is supposed to look like “LIST” or something but is coming back “ILTS” (or would it be “TSIL”?) due to byte-swapping issues. A quick scan of my sources doesn’t reveal any funky archiver behavior, and I can’t find any references to this type of error alongside “Intel” in the developer list archives. I searched my Nib files for “LI” and “IL” but didn’t find anything particularly interesting. The only comments I can find related to archiving issues in Apple’s documentation have to do with archiving bitfield values. What am I doing in common in both of my apps that would cause this behavior?

I will probably go back down there today or tomorrow to try to get some more information, but I thought it might ring a bell with somebody.

Update: I just noticed that my applications are using “Pre-10.2 Nib” format. I guess I never updated them, or something. I wonder if this could be the problem. I notice that my “objects.nib” file in the Pre-10.2 version does have a lot of “I”s in it, while the keyedobjects.nib file from a “10.2 and later” nib has a lot of “L”s.

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.