Journal

Why Technical Documentation Sucks

Jul 8, 2008

Based on a recommendation from Garr Reynolds of Presentation Zen fame, I just finished reading a book called Made to Stick by Chip and Dan Heath. The idea behind the book essentially distills down to this: "Let's look at bunch of great stories, speeches, ads, and proverbs, take them apart and see what makes them tick, then make a checklist of things that they have in common." Without giving the book a lengthy review (which it deserves), let me just say that I thought it was amazing. I highly recommend buying it or reserving it at your local library.

Now that I've read the book, I'm starting to see everything through a "Made to Stick" lens. The downside is that a lot of communication out there sucks (especially my own). The upside is that you instantly identify why good communication is good. Now this is all very well and good, but let's get to an example: technical documentation.

After the launch of MacYenta and the subsequent feature releases thereafter, I've started to get back into my Cocoa project, Aurora Drop. When I left off, I was just starting to wrap my mind around the Cocoa frameworks and feeling more and more comfortable writing code. Let me just say that I probably picked the worst time possible to cut myself off from that project in order to start a website. Now, after my hiatus, I'm having to re-map my mind into the Cocoa environment and, after a short few hours, am once again feeling the pain of re-acclamation. A major source of all this pain is the Apple docs.

Let me give you a bit of background. One of the features of my app makes use of "Quick Look thumbnails" which in layman's terms can be described as "those pretty icons in Leopard that show you previews of what your files look like". This technology is new and has its own programming guide to get you started using it. Here's an example paragraph:

The Quick Look daemon (quicklookd) is a faceless background application that acts as a host for the CFPlugIn-based generators. It communicates with the consumer side of Quick Look through a Mach port, and (as noted above) locates and loads generators when it first receives a request for a preview or thumbnail for a document whose format is not one of the native types. It conveys requests from clients to generators and returns their responses.

Let me start off by saying that I know at some level, technical documentation has to be a little explicit. With that in mind, however, I have to complain that a large portion of the programming guide reads just like this -- very dry and extremely bad at maintaining the reader's attention. While I was reading (and dozing off) I couldn't help but feel that it could be done better. It wasn't until I hit a good part of the documentation that I realized what was bothering me. Here's an example of the well-written piece:

With all the architectural pieces in place, let’s follow what happens when a client application such as Finder asks to display a preview of a document. The user opens a folder, displaying a list of documents of various types; some of these documents are of native Quick Look types and others are specific to certain applications. The user selects a document—say, a JPG file—and chooses the Quick Look Preview command from the File menu. In Quick Look the following sequence of actions occurs:

1. The client (Finder) sends a message to the consumer part of Quick Look requesting a preview for the document.
2. Quick Look sees that the document format is of a native type, so it loads the appropriate display bundle (if necessary)
3. ...

This paragraph actually maintained my attention, but why? Then it clicked -- it was a story! One of the items in the "Made to Stick" checklist is essentially "make it into a story". Readers (and listeners) are much more likely to remember what you said later if you told it to them in story form. Part of the reason is that makes for more concrete and visual language. We can follow along with the movie playing in our head and see what is happening. In this case, I can see the finder window opening and visualize the different files loading their icon one at a time. I can see the characters in the background (Finder and Quick Look) talking back and forth -- making requests and getting responses.

Granted, no one will mistake this stuff for Shakespeare, but it did make a very bland document more interesting and easier to retain. The next day, I saw an even better example: a post by Wil Shipley about bug fixing. One of the great things about Wil is that he is extremely good at turning a boring topic like bug fixing into an interesting read. Reading through this latest post, I realized he was doing the same thing as the Apple documentation -- he was telling a story. It was even divided up into parts (including an intermission!). And you know what, I'll remember Wil's discussion of bug fixing long after I've forgotten exactly how Quick Look's internals work.

Summary

1. Whenever you're writing something for someone else that you want them to retain, it helps to make it into a story.


2. If you've ever needed to speak to anyone in your life (and expect to again), go buy Made to Stick.

MacYenta.com

Jun 17, 2008

Holy cow! So yeah, it's been a LONG time since a post. In that time quite a bit has changed including a new job programming for the web with the awesome folks at RainStorm Consulting. I feel very honored to be working there and am looking forward to all the cool projects we're working on.

Now, as the title suggests, I think it's worth mentioning that I've launched a new website called MacYenta which is meant to facilitate the coordination of Indie Mac Designers and Developers. The community of late has been going through quite a change what with the addition of the iPhone platform. Given all that, I started the site in the hopes of organizing the chaos to a certain extent. The response has been unbelievably amazing! Since the site's launch at 1am on Saturday, there have been over 230 registrations -- people looking for a partner, people looking for work, and people looking to hire; everyone for the Mac community. I'm honored to have profiles from some of the Indie elite including Craig Hockenberry of Icon Factory, Buzz Andersen (a former Apple employee and community icon), and Rich Siegel of Bare Bones — just to name a few!

Given this huge surge, I'm feeling a bit like the community -- interested in maintaining the indie feel while exploring all these new arenas for Mac development. I've got quite a few upgrades coming for the site to help people navigate the mass amount of profiles. Hopefully it performs the job I've designed it for and the community becomes better for it.

If you have any questions about the site, feel free to email me () or follow macyenta on twitter! Thanks everyone!

iPhone Review

Sep 11, 2007

About 2 weeks ago, I bought a refurbed iPhone from Apple for $100 off the original price. Lest you think I'm about to go on a tirade about the $200 discount that followed the next week, let me make perfectly clear that other people have covered that well enough. No, this will be a review of a few things I've noticed as a casual user of the iPhone.

To start off, it's amazing! As an interface geek and Apple fanboy, I can't get enough of it. It is the best cellphone I've ever seen. I went into a U.S. Cellular store a couple of days ago only to be reminded yet again how much of a bubble I live in. All other cellphones looked like tired pieces of electronics from 1990, save the RAZR which (at least from an industrial design standpoint) looks like it came out this century. The iPhone's design and software are leagues beyond anything out there. There's no doubt Apple's going to make a ton of money with these.

Having given my general assessment, here are a few things that I've found while using it that I find really useful.

Sleep/Wake.
It's amazing how important being able to have instant-on is with a device. I'm addicted to the little button. Not only that but ever since I saw the slide gesture back in January, I fell in love. Getting into the phone is one of the most pleasant experiences using it (and that's a good thing).

Photos.
The photo app is the best way to introduce people new to the iPhone to the wonders of the interface. It's gorgeous. They've even paid such attention to details that if you grow a photo by spreading your fingers apart and then you drag your finger across to see the next photo, it looks and works exactly as you'd expect it to. The large photo maintains its size and you can see the other photo in-line right next to it. If you don't pull the current photo over enough, it "rubberbands" back into place. Fantastic feedback!

Camera.
My old phone is a bona-fide POS, so I haven't had the luxury that many other people have been enjoying over the past few years by having a camera always on-hand. Then again, those people who have used camera phones in the past probably feel as though it has been a hinderance more than a luxury given the lack of good synching support, but I digress. Having the camera around is awesome. I've taken more pictures with it than I have in a long time -- I've fallen in love with photos all over again! Regardless of quality, it's nice to capture events that would have formerly been relegated to the deepest corners of my horrible memory.

With all those out of the way, here are a few things that could use some help.

Mail for Gmail.
Hands-down, Mail for Gmail is the biggest disappointment (outside AT&T reception in Maine) that I've found. I've had my Gmail account for a long time and have used the extremely convenient "Archive" function to my benefit storing away thousands of messages for later retrieval if necessary. Why on earth would I POP those messages on my mobile device? Honestly, whoever made it so that this happens should think about a new job. That is awful! Sure, there are supposed to be ways around it (none of which I've actually gotten to work), but why in the world would this be the default?! It's so frustrating! Gmail either needs iMAP support or to fix whatever the hell is wrong with this, and they need to do it soon. This is ridiculous!

No RSS? Seriously?
I must admit that I'm quite surprised that they didn't include an RSS reader. I would think the kind of people who need to get e-mail at every second of the day would be strung out if they didn't have similar access to their news without visiting each website individually a la circa 1990s. I really hope they fix this or open an API so that someone else can -- Brent Simmons, I'm looking at you.

Headphones controller.
The headphones that ship with the iPhone are pretty cool. They have a built-in microphone so that if you're listening to music, you can take a call seamlessly. Very nice! Another interesting touch was to include a controller in the same place. So, if you want to pause your music, you just pinch together the button on the cord and it happens. Double-pinching advances to the next track. Very, very cool -- at least in theory. What I find unfortunate is that the microphone/controller is located directly in a blind spot. When I'm listening to music, I can't see it at all, so I'm groping around trying to find it along my cord. Not only is this awkward to do, but quite frustrating since usually this is meant to provide quick-access on the spur of the moment. I can see why they put the microphone there, but my question is, why not put the controller in the earbud itself? It's much easier to get to. In fact, it reminds me of Fitts's Law which talks about the speed at which certain actions can be triggered based on where the controls are located. A great example of this law in use is the corners of a Mac OS X screen being used to trigger Expose, etc. They are extremely easy to target at a moment's notice.

Coverflow.
I'm surprised how context-insensitive Coverflow is on the iPhone. For example, if I am looking at all the albums for a particular artist on my iPhone, and I turn the iPhone into landscape mode, I'm surprised that it doesn't only show me album cover art for those albums in the list I was just on. It only makes sense. Another small issue I had with Coverflow involved Shuffling all my songs. While listening to a particular song, if I double-pinched the headphone controller to advance to the next track, if I was in Coverflow, the display wouldn't flip down the album art line to the new album that I was playing. Instead, it just sat on the same album. Doesn't make much sense to me.

I could go on and on about the iPhone (just ask my wife). And, as I said before, there's little reason not to own one, unless you can't really justify the cost of it and live in Bangor, ME where the AT&T reception is horrible. But, even then, it's quite tempting! :)

Software Upgrade Restarts

May 1, 2007

So Apple put out a security update today for Quicktime. Being the nerd that I am, I downloaded it right away. Since the update was so large, I obviously went about my work by opening my RSS reader, some tabs in Safari, etc. In a short time, the update finished downloading, installed itself in the background and then prompted me to restart the computer.

When I first learned computer stuff, it was on a PC. Unfortunately, it is here that I learned poor habits that have taken years to break. One such habit is closing out all open application after a system update that requires a restart. So, as soon as I see that "Shut Down/Restart" dialog, I start closing down whatever it is I'm working on, disconnecting from any network shares I may have and wait while everything clears out. Then I click the "Restart" button. Once the OS has gone through its full restart, I take it upon myself to re-open all the applications that I had previously opened.

On this particular update from Apple, I caught myself as I was just about to close out of my browser. "Surely this is an old PC habit coming to life," I think. "No doubt I can leave all my applications exactly as they are and when OS X restarts, they'll all return to their previous locations." Being ever the pesimist, however, I made sure to note exactly what sites were open in each tab so that if such a thing were not to happen, I could return from whence I came.

Sadly, this is where Apple failed me. After the restart, nothing re-opened. "Surely this is some mistake," I thought. Unfortunately, it is true -- OS X will not return to its previous state after an upgrade restart. And that makes me wonder: why not? There can't be much of a technical limitation preventing this. The window manager in OS X should be able to write down the positions of all windows and panels open, then re-introduce them to their previous locations. Why doesn't this work? Heck, other applications that auto-update themselves using the Sparkle framework in OS X have the same issue! If I update TextMate and restart it, it doesn't remember the files I had open. What a joke! I only hope that my request for such a thing will be picked up by those I condemn and that we may eventually see a beautiful, usable future where this "bug" no longer exists.

The Apple iPhone

Jan 9, 2007

Sure, let it be a new product announcement from Apple to induce me to blog again after so long!

Let me be the first to say that I did not expect the iPhone today. Looking back at Apple product announcement history, I expected an Apple Special Event to be held in honor of a new product line, but I am very happy with the results! This is by far, without hyperbole, the best keynote I've ever seen Jobs give (even with 1 or 2 technical glitches) and the best product I've ever seen them demo.

Not long ago, we were talking at work about Apple stock and how far it could go. My boss, Scott (a long time Apple owner), talked about when the first iMac was introduced and how he thought they had surely reached their apex and sold his stock. He reminisced about how much money he could have made if he cashed out now. The reason this subject was brought up at all was as an argument against my belief that Apple may have reached the pinnacle of what the iPod can be and that I didn't expect long-term stock growth for the company. I was wrong.

Apple is obviously not sitting on their butts waiting for the next curve, they have been thinking about that curve for the last 2 or 3 years working on the iPhone; and the results are true to form, in Apple style. The iPhone is fantastic!

Anyway, I guess I'll leave this post with two of my favorite quotes from today's event:

"I skate where the puck is going to be, not where it has been." - Wayne Gretzky, quoted by Steve Jobs during the keynote.

"Don't be the first to get it wrong: Be the only one to get it right at all." - Leander Kahney, talking about how although Apple was late to the phone game, it turns out they were the only one really playing.

Disco

Sep 16, 2006

If you haven't heard of Disco, the latest app from the guys behind the ultra-sexy AppZapper, I suggest you check out their blog. Though scant on details, it is being hyped as just as cool (if not more so) than their previous achievement. At this point it seems to be burning software of some kind, which, although I'm not in the market for, I'd definitely like to see more of. Given their history of creating a simple, fun app, I'm excited to see what Disco has to offer.

See one of the designers, Jasper Hauser's Blog for details on how quickly they sold out of their original 2000 pre-order copies from the discount Mac software store MacZot.

OS X Leopard

Aug 17, 2006

So now that Apple's World-Wide Developers Conference is over with, we are seeing a few screenshots of their upcoming operating system, Leopard, emerge. While comparing those shots with my current operating system, OS X Tiger, I started paying attention to the minute changes made between the versions. It reminds me that a true artist relishes in the details. Most interestingly, I found that even where a small change could easily be tossed in and just "appended" to the software, they seem to have taken great strides in polishing it so that it looks like it belonged there all along. Such attention to detail is really inspiring. It reminds me of a post I once read showing the difference between the Mail icon in Panther as opposed to the Mail icon in Tiger. Apple quite easily could have left the icon alone and no one would have noticed. Instead, they made an extremely subtle change to the orientation and/or shading just to make it that much better. It just goes to show that everything can be improved and the only bad software stays stagnate.

A quick Google search didn't reveal the post on the Mail icon. Perhaps I'll link to it when I actually get this one under way.

Comment Spam

Aug 17, 2006

I've been getting some comment spam over the last few days, so I finally decided to do something about it. There is a small text box in the comments area now with instructions on how to make sure your comment is posted. All you have to do is type 'NO SPAM' in the box before submitting and you are good to go. This will keep random bots from being able to randomly submit the form with gibberish and links to stupid websites.

Right now there is no error checking, so if you don't type 'NO SPAM', you will just lose the comment you were about to make. I'll hopefully find time to polish that up a bit in the future. (Though with the number of comments I get, I doubt it!) :)

WWDC '06

Aug 7, 2006

Well, I actually made it through work today without hearing a single bit of news about WWDC. Then again, I did strictly warn my co-workers (and bosses) not to say a word when I was around as I much prefer the suspense of going home and watching the webcast. Yes, I'm an exteme Apple geek.

So, after waiting all day and making dinner, I sat down with Sarah (who made it through much more of the keynote than I thought) and suffered through the web traffic to get a glimpse of Apple's latest hardware and software.

Altogether I enjoyed the news, but for most of it I had that nagging feeling of hearing a lot, but seeing very little... this feeling is really un-nerving for Apple. I mean, Steve usually gets up on stage and tells us about great new technology that they have and relishes the chance to say that it's "Available Today". But here the keynote has come and gone and we only saw a couple very brief demos of OS X Leopard. Not only that but one of them crashed and backups had to be used. Most of the time, they counted down the features by putting up bullet points and just talking about them with very little visual to go with it. To be honest, it felt like smoke and mirrors. The second piece that makes me uneasy is the ship date on Leopard -- Spring 2007. For the last 5 or 6 years Apple has been rolling out consistently great revisions to their operating system. In fact, they've kept a dazzling 1 year average per upgrade -- unheard of in the software industry. But here we are, over a year after Tiger shipped in Spring 2005 and barely seeing anything. Not only that, but if Leopard ships in Spring 2007, they've taken twice as long to get this revision out the door than normal.

This is either very good or very bad. Good would be if Apple chose 10.5 and the arrival of Vista as a time to really put out the best they can offer and raise the bar extremely high. The stuff could be so revolutionary, they can't even tell us about it because MS will get their copy-cat mits on it. So they'll wait till Vista ships at the same time they release Leopard and be able to really let the innovation shine through -- after it's too late for Microsoft to implement.

Bad would be if the whole thing really is smoke and mirrors and Apple has run out of ideas. So they've come up with some stuff they think is interesting, but haven't figured out a way to implement it. While this seems a bit excessive, a lot of the technology shown at WWDC in Leopard was far from revolutionary. Backdrops for iChat? Seriously... that is tacky. And adding notes to Mail? Does that really even make sense? Why not put them in a separate application? Not only that, but they act like they invented the idea of virtual desktops; something which I know has been in Linux (my God people, Linux!) for many years. I guess we'll just have to put our hopes behind the company that seems to have an endless supply of surprises and the man who has lead two industry revolutions for the most innovative company around.

One thing that gives me faith is Time Machine. It reminds me that Apple engineers and designers are, at their core, artists. Time Machine is the feature in Leopard which allows the user to open a folder (or application) and scan back in time to find something that used to exist. Two clicks later and it's right where it was. Seamless, obvious and beautiful. That is the innovative Apple that I know and love. That is what gives me hope for the future.

Update: My Powerbook, which was recently repaired by Apple over the course of 3 weeks, just had a key from its brand new keyboard fall off... and it won't go back on... now, I'm starting to worry!

Magic Hat

Jul 28, 2006

I've noticed a pattern in working with OS X. I'll go on the net and download an audio clip or a video, or I'll take a screenshot which automatically appears on my desktop. So then I'll take the file in question, find the appropriate built-in folder like "Movies" and slap it in there. Or if it is a piece of media that can be managed via a more specific application like music in iTunes or pictures for iPhoto, I'll open up the app and import the files by just dropping them on the app. Then, I'll take the files on my desktop and drag them to the trash.

What I'm wondering is, couldn't this be simpler? I mean, they already have native apps and folders dedicated to different types of media: iTunes (music and movies), iPhoto (pictures), Documents folder, the Applications directory, etc. It's straight-forward to figure out what file goes where. Why not have a magic hat in the dock that we can just drop files on. Drop a photo from the Desktop to the hat and "Bing!" it imports into iPhoto for you... but without opening iPhoto. Just a friendly notification comes up saying "Picture 1.png was successfully imported. Click here to open iPhoto." Cause, as easy as it is to import pictures directly from Mail or Safari, iPhoto still opens, which, for many people, can take quite a while depending on the size of their Library. Why can't it just slide in through the back door and let me get on with whatever I'm doing? And what about music? Can't I just drop a music file onto the same icon and have it import into iTunes? Or drop a new application I've downloaded off the net and have it put into Applications? What about documents from Pages or Microsoft Word? They have a pretty straight forward place too, why not use it? The issue is especially simple with the advent of Spotlight's "instant" searching of the hard drive. If we really want to get rid of folders, we should make it easy to just have something put away without even thinking about it. I mean, it can't be that hard to deteect what each of the files is. Heck, even let the user decide for each file type, where they'd like it to go. Drop a vCard and have it thrown into Thunderbird or Address Book. Toss in some iCalendar events and have it put into iCal. It'd be like having every app in your dock at once, but the program would be doing the routing. No thinking to it. And if you need to make some alterations before it gets tossed into the mix, click the button that opens the app and get to refining that meta data.

It can and should be this easy.