Tewha Links and writings on software development, mostly for iPhone and Mac OS X.


Apple's developer documentation website is horrible

Isn't anyone at Apple even mildly embarrassed about how poor the ADC search results are?

Like everyone other Mac developer (at least, those not using a seed... no comment otherwise), I've been bit by the Mac OS X 10.5.7 bug that causes Xcode to crash almost every time the documentation viewer is used.

Now I'm a reasonable guy. I get that a Mac OS X update has to be thoroughly tested. I wouldn't want it otherwise. So let me get this off my chest right away: it isn't the bug itself that bothers me.

Xcode 3.1.3 shipped after Mac OS X 10.5.7. So it should have been pretty easy to add code to Xcode see if the developer has executed a defaults write com.apple.xcode dontevershowthefuckingdocviewer 1 and then never show the documentation viewer, so I wouldn't lose unsaved work every time I forgot and tried to open it.1

And in the future, the documentation links should be handled via an URL type that can be handled by another application.

And, oh yeah:

Why is the documentation viewer embedded in the IDE?

Splitting the documentation viewer into a separate application would make a lot of sense. Browsers crash! If it wasn't this, it would be something else that crashed the documentation viewer. This was predictable. This was, dare I say, expected.

But what really, really makes me angry is the developer site. The content is generally pretty good, but the search engine is horrible:

  • Fix your summary so it's actually useful.

    Apple's summary:

    appleGoogle's summary:

    google

    There's just no comparison.2

  • I don't need to see every single empty redirect. Showing the same effective document multiple times is just random clutter.
  • There are better ways to represent the format of documentation in search results than just including it in the URL.
  • Add up those last two items, and you realize: I don't need PDFs in the search results. PDF should just be linked to from the documentation itself.

I'll update this when I have more points. The bile has receded enough for me to code again.

  1. Maybe use a different identifier for it. [↩]
  2. Google, you rock. [↩]

iPhone SDK: UIKit vs WebKit

Earlier, I wrote that I don't have much comment on Gruber's post on iPhone web apps. It turns out I was wrong.

It took me a while, but I realized after making that post that I needed to reconsider what I was doing for iPhone development1. See, I have an application in mind for the iPhone. I originally planned to develop it for the web, but I need to reconsider that.

There's a bunch of advantages to sticking with the web SDK:

  • Centralized data authority. Users will never need to worry about whether their desktop computer or their iPhone has the latest version of their data.
  • No data management for users:They never need to worry about backups, because I can backup everything automatically.
  • Fully cross-platform2: All other things being equal, a bigger market is better, right? Sure, I'd want to do some customization for the "desktop version" later, to take advantage of the larger screen, but it wouldn't be a rewrite by any means.
  • SDK available today: A chicken in the hand is worth at least a dozen unknown birds squawking in a tree.
  • Automatic updates for all! Hooray! This is especially relevant to me, because I can see tweaking some of the algorithms behind the scenes for many years.

For my application, I can see these advantages to a UIKit SDK application:

  • Better performance: web page downloads over AT&T are going to take a while regardless of what else I do.
  • Richer interface: despite WebKit being pretty darned capable3, I probably wouldn't be able to do some of the more complicated animations or graphical manipulation that I wanted to do.
  • Offline use: except some of the things I want to do would likely require a connection anyway4.
  • More interaction methods: This is the only one that really bothers me. Being able to flick between pages and respond to rotates easily is important for an iPhone application. I hope Apple has something up their sleeve on this front.

How does it all stack up? I think I'll be doing the development using the web. Nothing's really changed, but now I've thought it through and feel comfortable with the choice.

Given that decision, I'm done. If I decided on UIKit, I'd now be wrestling with whether to unlock my iPod touch5 and start looking into third party documentation on the SDK to get an early start. I'm not sure this would really be a head start, as there's probably quite a few others who will decide (or have already decided) to take this route.

  1. Like Gruber, I'm just going to use iPhone as the generic term for iPhone or iPod touch. [↩]
  2. In the sense of the software being able to run on all modern web browsers, I mean. [↩]
  3. See PopCap's Bejeweled, for instance. [↩]
  4. This raises the question of what exactly the iPhone SDK can and can not do. Will it have full network connectivity? [↩]
  5. I'm not really breaking my rule here. My device is, specifically, an iPod touch. [↩]