ADC Documentation Bomb

March 8th, 2006

Apple’s documentation team just keeps getting better and better. Not only is the writing clearer and more connected to real-world applications than it has been in the past, the team seems to be getting prolific! Today they dropped a huge update on their site, including a bunch of brand new titles.

The completely new documents:

  • Cocoa Fundamentals Guide – This looks like a new “first stop” document for developers just coming to the platform. But perhaps more importantly for the rest of us, it contains a chapter completely dedicated to Design Patterns and how they relate to Cocoa. Sweet hallelujah! Many developers have been waiting a long time for documentation like this to start coming out of Apple.
  • Cocoa Drawing Guide – This appears to tackle many of the details about how one goes about exposing the advanced facilities of Quartz through a Cocoa-based application. The Advanced Drawing Techniques appears likely to eliminate a lot of mailing list confoundedness. Hopefully the fact that this document shipped with “Alpha Draft – Confidential” at the bottom doesn’t mean it was a mistaken release.
  • View Programming Guide for Cocoa – It just keeps getting better! This one discusses the high-learning-curve tasks associated with creating a custom view in Cocoa, and again includes an “Advanced” section as well as an “Optimization” section for those “wish I could chat with an expert” moments.
  • Scroll View Programming Guide for Cocoa – It may seem strange to find this new document in the midst of others with much larger scope, but I can see how this will come as a great relief to people who have beat their heads against their keyboards while trying to get scroll views to behave as expected. In particular, the concepts discussed in synchronized scroll views should help a lot of people out.

And one major update:

  • Cocoa Scripting Guide – Apparently the result of a merge and rewrite of two previous scripting documents. As anybody who has added scripting support to an application knows, more documentation is always welcomed.

Exciting times. Thanks for the update, Apple!

Red Sweater Links

March 4th, 2006

Those of you who have been reading for a while have probably noticed that I don’t spew dozens of short one-liner entries with a link to something cool and a quick typo-laden comment including my opinions about it. I hope you appreciate this. Sure, it would be quicker to get through than some of my lengthier articles, but I like to think of this as a place where you come to learn something or think about things in a new way, not simply as a bouncing pad to the rest of the universe.

Still, I have the urge to share and comment. Who doesn’t? I’ve been planning for some time to implement a split-personality style solution, similar to Daring Fireball‘s, where the short links live separately from the longer articles. If you’re the kind of person who just wants to read the lengthier, more thoughtful (if I’m having a good day) articles, then do nothing. You’re the one being protected here – nothing will change in the main blog. If however, you wish your NetNewsWire subscription list was just a bit harder to navigate, consider adding Red Sweater Links to your bookmarks list, or subscribe to the RSS Feed.

The implementation of this feature includes some lessons for software developers. See – I’ve been putting this feature off for months for “no good reason.” Specifically, because implementing this properly requires features of WordPress that don’t exist and skills or experience that I don’t have. Ideally, I’d like to have WordPress manage the list of links similarly to how it manages articles in a particular category, but as I said, I don’t want to “taint” the mainline blog. I spent a lot of time thinking about how I might do this. Implement my own custom link management software. Modify WordPress to allow exclusion of a category from aggregate view. Expand the “Links” functionality of WordPress to support more metadata. Look into the version of WordPress that supports multiple blog installations. Blah! It’s too much for my little head to take!

Red Sweater Links is implemented the way many new features are implemented: as a nasty hack that works. I don’t have time to figure out how to do this right. So I made a copy of my blog and embedded the copy within itself. Sick, huh? Good enough for 1.0.

Note: You’re not hallucinating. This feed previously described the new links feature as “Dinky Links.” I thought this was cute for about 5 minutes.

The Future’s Not So Bright

March 2nd, 2006

I read Jason O’Grady’s comments (via Daring Fireball) on the keyboard backlight of the MacBook Pro with some surprise. I am the proud owner of one of these new machines, and his experience doesn’t exactly match mine.

Granted – I don’t have a PowerBook G4 to compare against – I haven’t owned another Mac laptop since my iBook G3, which certainly didn’t have any of these fancy backlighting features. But the staring into the sun metaphors alluded to by O’Grady seem really far-fetched. Unfortunately, he only shows us images of the two laptops at “half intensity,” while mentioning in passing that the MacBook Pro’s “keyboard backlight set to one bar is brighter than the keyboard backlight on the PowerBook set at 16 bars.” Where are the pictures for this – the interesting claim?

I’m also skeptical because the keyboard images are being shown out of context. We don’t normally stare down into our keyboards without the (usually more powerful) light of the laptop display to soften the relative intensity of those keyboard lights. I thought I’d contribute another set of photos which may at least offer hope to those of you who are starting to worry about SPF factors in relation to your future laptop:

The first is at maximum keyboard backlight, the second at minimum. Obviously, my photos might be deceptive, too. But all I can say is that dim version looks “pretty much” the same as it looks in my office. Maybe O’Grady got a defective keyboard? I would like to see a picture of this retina-burning “lowest setting.” If the dim version shown above is brighter than the maximum brightness of the G4 keyboard, I’d say it’s the G4 that was defective!

Five Things I May or May Not Know

March 2nd, 2006

To mark the occasion of my 100th (!) post, I’m recalling some of the major points of wisdom I’ve accumulated over the past ten or so years. Not to brag or anything, but in spite of my slacker attitude and a recurring assumption that I’ve “known everything” all along, I’ve actually learned a few important things along the way. Or at least, I think I have. I usually find myself jabbering on about these opinions to people who could care less: my helpless friends and family. Perhaps by writing them down here, somebody will actually get some use from them.

At first I thought it would be fun to scrape the barrel for 100 points of wisdom, but it turns out I don’t know as much as I thought. Plus, some people think my entries are long enough as they are! I’ve settled on five fairly general thoughts about the business and technology aspect of our lives. These opinions represent wisdom that has helped me achieve a fairly respectable level of success. If you’re looking at the glass half-empty and need a bit of inspiration, maybe some of these observations will excite a motivational bell for you.

Thing 1. Managers are soul-sucking zombies.

Managers are good people – well, most of them are. But they generally reached their position by giving up something they love. Somebody – usually another soul-sucking zombie, convinced them that they should stop doing whatever they were doing and become a manager instead.

Few children will state that they “want to be a manager” when they grow up. That’s because managers – in spite of getting things done, don’t “do” anything. Nothing you can explain to a kid, anyway. They don’t put out fires or bust bad guys or hit home runs. They get other people to do that for them. They’ve become the creative un-dead, and while performing valuable tasks like protecting you from other managers, raising your pay, and sending you on expensive business trips, they also try desperately to pull you into their miserable way of life.

Disagreements between managers and “individual contributors” usually boil down to a difference of opinion on the meaning of “compromise.” Individuals are relatively uncompromising, especially when it comes to doing what they love. Managers hate this, because it reminds them of how they used to be before they got promoted. One of the qualities of a great manager is an ability to compromise. But too often, this means letting life take a crap on you and smiling about it.

Thing 2. Your co-workers are dumber than you think.

Usually when you enter a new workplace, you can tell pretty instantly whether everybody is really smart or really dumb. It only takes a few brilliant quips or idiotic blatherings to pigeonhole a co-worker firmly into one camp or another. Or so you think. Most people are actually neither as smart or as dumb as they first appear.

A phenomenon occurs when people work together for a long time. They discover each other’s secret talents and secret flaws. This is good for the team, because it allows for more efficient delegation and group-attack when the toughest problems arise. But when a new employee comes on board, everything is thrown into disarray. If the new employee is senior, she receives a heightened presumption of brilliance by the existing team members. Because they haven’t had the benefit of observing her occasional failures over the past ten years, she is defined only by her impressive resume. On the other hand if the new employee is fresh out of college, regardless of whether he is the next Einstein of the field, he is presumed to be mostly ignorant by the team.

The junior employee enters the team with a particularly distorted view. He’s never been in a real job before. He’s not quite sure how it all fits together. Everybody on the team has well-practiced statements of grandeur that elevate their appearance of intelligence. They’ve been practicing the same industry jargon for years, so it rolls off the tongue with aplomb.

As a junior employee, you must appreciate that most people are just average – even if they appear to be geniuses. As you develop a stronger sense for your new co-workers talents, the presumed geniuses of day 1 will slowly fall by the wayside. If you’re lucky you’ll find some true geniuses to mentor you, but you should be encouraged by the reality that many people “at the top of their field” are downright stupid. That means you can really excel if you stick to your guns.

Thing 3. Simple is best.

There’s good wisdom behinds the famous KISS acronym (“Keep It Simple, Stupid”). It was obviously invented by somebody with a bit of experience behind them. It’s become such conventional wisdom now that many college grads probably think they “get it” from the start. They don’t get it. I don’t get it. No matter how hard you try, you won’t get it. It’s like yoga – you practice your whole life, always improving but never perfect. How does undue complexity manifest itself in the software industry? Two major pitfalls are premature design and overindulgence of customer whims.

Premature design is the variety of complexity that causes one of your “not as smart as they seem” co-workers to hole up in their office for weeks on end – emerging “victorious” with something that looks and acts exactly like the software did before. “But it’s totally redone! See, we could implement Pac-Man with this thing now!” But what if – and this is a long shot, I know – nobody wants to implement Pac-Man with the time-tracking web application?

Indulging the customer is even harder to reign in. They do, after all, pay the bills. The more bills a customer pays, the more complexity they get to inflict on your application. But you must resist this as much as possible! Joel Spolsky identifies software that evolves from over-obedience to customer whims consultingware. Basically, the app is as crappy as the customer wants it to be. I’ve seen projects where literally any request made by a customer (paying or otherwise) resulted in a change to the application’s source code. Every unwarranted change to please a single customer is done at the expense of every other customer, who doesn’t need or want the features.

A little bit of planning is a good thing, but design for its own sake is a mental illness that many developers suffer from. A little bit of tough “imposed managerial compromise” can go a long way towards treating this.

Thing 4. The customer is always interesting.

Although the customer’s whims should not be acted on willy-nilly, they must be considered. Carefully. Whatever your customer is telling you is a gift. It’s a peek into the mind of the world. A deeply religious person may find their spiritual path altered by a “message from God,” or some other divine intervention. For businesses, these unpredictable course-steering messages come in the form of customer support emails.

The biggest problem with customer communication is that whatever the language of your business is, your customer doesn’t speak it. If you’ve ever tried to get reimbursed for an out-of-pocket medical expense, you probably spoke with at least a half-dozen insurance industry wonks, each of whom studied your case carefully, verbally annotating their progress by rattling off the names of standardized medical forms and procedures. You sat there glazed-eyed, simply hoping to get your damn refund. Remember that feeling the next time you respond to a customer’s email. They are desperate for help, and they aren’t sure how to ask for it. If they sound like a Texan asking for directions in Chinese, it’s because they don’t speak your company’s language!

You have to sift through the coded communication for the real information. If you find yourself muttering, “idiot!” about a customer, consider applying the insult to your company, instead. How could my company drive a person to behave this way? Could we prevent future customers from behaving this way by fixing our product? Often a request for a “ridiculous feature” is code for some other problem. A customer asked me to add a feature to FastScripts allowing it to be launched multiple times. A devastating feature that would be! Digging a little deeper, I learned that the customer’s instinct was to work around a shortcoming of the application: that only one script can be running at a time. By struggling to understand the customer, I developed a ridiculous request into a meaningful TODO item.

Thing 5. Everything you may or may not know is temporary.

Everything you know, whether you’re fresh out of school or enjoying an active retirement, will one day be turned on its head. Nothing’s sadder than a know-it-all who refuses to admit when they’re wrong. It’s a real shame because often these stubborn individuals are real geniuses, not even the fake kind alluded to above, but they are geniuses who get sidetracked. Patting a genius on the back is dangerous because, despite their brilliance, they’re liable to make the fool’s move of assuming they’ve reached a permanent apex of wisdom. They figure if they’re so smart, then everybody else’s opinion must be wrong. Yikes!

This syndrome causes UNIX geniuses to continue using vi and nroff for all of their word-processing needs, in spite of the advent of the GUI. It causes procedural programming geniuses to shun objective-oriented languages, because they “know how to do it in plain C.” It causes marketing managers to insist on investing tons of money into marketing, because free, viral web marketing didn’t exist when they got their MBA.

Almost every thing we know to be wrong today was once right. And most of what we know today will one day be wrong. Knowing this separates the super geniuses from the mere geniuses (not that I would know, I’m just an observer). The advice included in this article is fairly timeless, but I don’t doubt that one day it too will be obsolete. If you’re lucky, and can grab hold of just a few seriously smart approaches to business and technology today, then you may or may not be on the fast-track to success.