It occurs to me that the language of our profession is in need of a new term. Heaven knows, we invent plenty of ’em every day, but apparently we’re still missing this one. Whereas, for decades, the gurus have always turned away luser questions with the advice to "RTFM" (usually glossed as "Read The ‘Fine’ Manual"), that’s not how it’s done any more. As we all know by now, your first recourse with any technical question is Google. So, "Google The ‘Fine’ Manual"!
It may be that jet-lag is actually good for something. As I awoke this morning, my body in Chennai, India, my circadian rhythms in … I really have no idea where … the letters burned before my eyes: GTFM. Google The ‘Fine’ Manual. Interestingly enough, I appear to be the first person to achieve this enlightenment (I’m pretty sure of that … I Googled it).
When I first studied computing, on the IBM 1620 ‘CADET’ ("Can’t Add, Doesn’t Even Try"), and later on IBM’s Series 360 and 370, we had real manuals (from the Latin manus, "hand"). You picked them up by hand. In fact, you had to use two hands. A fork-lift would not have been out of place. The documentation of the day was famous for its thud factor, if not always for its clarity, readability, or helpfulness.
But then, manuals moved to PDF, and came on the CD or other distribution media. Then the Web rolled over us all, web publishing took over, and quickly we realized that merely finding the information had become harder than just turning to the book shelf. We evolved links pages, curated information archives, web crawling, and page scoring. The web co-evolved with another revolution in computing: collaboration. Through Bulletin Board Systems, through e-mail, over the Internet, in global-access version control repositories, and nowadays in blogs, open-source work-styles began to produce more and more of the software we use every day. But the open-source ideal transforms more than the contribution model, it also transforms the documentation: since so much of the design work is available on line, relatively little formal documentation is actually needed. Instead, you can read the actual discussions that led to a decision, the actual experiences of users, and the actual reports of problems not yet fixed.
While much of this kind of documentation lacks stylistic polish, and it can be a bit spotty, it scores over traditional documentation in one key area: candor. The blogging community, in particular, manufactures candor in ton-lots. Where that fork-lift-enabled IBM documentation of my youth was sometimes so stuffy you couldn’t make out what it was actually saying, e-mailers and bloggers take pains to ensure you’re left in no doubt. And frankly, candor in documentation is a good thing, too-little appreciated in the old days of tree-killing, back-breaking dox. And the diversity of styles, second- (and third-, and tenth-) opinions, alternate takes, and further links leads to a far richer, and ultimately more helpful "documentation book shelf." If you’ve been clicking my references as you read, you’ve seen a sampler. My browser even allows me to Google a word in my text from a context menu (I bet yours does, too). Makes writing an article like this almost embarrassingly easy!
To take an example: just recently, I found that a program of mine was sometimes deadlocking. I dug deep enough to realize the problem: using a messaging system called Apple Script I was sending a request from program A to program B, to satisfy which program B needed to send an event back to program A … who was patiently waiting for the result of the first request, and so never heard the second. Deadlock. To resolve this, I needed to put some of this processing into another thread. Not all Apple APIs are thread-safe, however, so I resorted to the old-fashioned RTFM. But Apple’s documentation for Apple Script says not one word about thread-safety … the word "thread" is not even used. In a field like thread-safety, that’s a bad sign, because it doesn’t happen by accident, and if you take the trouble to build it in, you usually brag about it. But there are nuances and degrees of thread-safety, and I was prepared to provide at least "stack-bound thread safety" (that is, to ensure that this class was only used from a single thread, albeit not the main thread), which is often sufficient for non-thread-aware code. But was that enough in this case? TFM was silent.
Enter GTFM, which quickly led me to this:
I don’t like the NSAppleScript class because it is extra un-thread-safe. That is to say, you can only use it on from the main thread (hint: performSelectorOnMainThread:). No amount of @synchronized blocks will keep you from crashing (intermittently!) if you use an NSAppleScript anywhere else.
OK, well, a nice helping of candor, a minor typo or two, and a direct answer to my question. You’ll never find a paragraph like that in stuffy old bookshelf documentation! Even better than that, the paragraph goes on:
There is a workaround that won’t block anything, but the cure is worse then the disease. You can use an NSTask to have the osascript program interpret the script for you. This won’t block anything, but it will be take a long time, and is resource intensive.
And best of all, that "NSTask" link is not a link to Apple’s TFM for the class of the same name, but rather to a convenience wrapper-class, by this same author, that makes the whole thing into a drag-and-drop instant solution! Since my application is not performance critical, I can live with the warnings. From "quandary" to "solution," in one GTFM.
So, get with the new millenium: GTFM!