How (Not) to Distribute Software Online

The Internet has revolutionized the distribution of software: search for what you need (or want), download it, install it -- instant digital gratification!

And yet, some developers still manage to make this process a highly unpleasant experience. Here's one example of how not to distribute your software. Plus a few ideas to consider when publishing your own software as a download.

When I recently treated myself to a new iMac (slightly bad timing, as it turned out yesterday...), one of the items on my list of "must-install" software was a current driver for my Kyocera FS-920 printer. Thanks to a decent search feature on their German support website, finding the required driver was fairly straight-forward. Among the huge list with all kinds of drivers for all kinds of operating systems, here's what is offered for the Mac-using populace:

Kyocera use a not-quite-so-consistent naming scheme for their printer drivers.

Although the entries under "Beschreibung" and "Dateiname" -- which is German for "description" and "filename," respectively -- aren't all that consistent, you can still spot the driver for OS X 10.5. Hover the mouse pointer over those red info icons in the right-hand column makes tooltips with more information pop up, pointing out that "This driver can only be used with Macintosh OS X 10.2. and 10.3.", "... OS X 10.4", and "... OS X 10.5," respectively. Ah, thanks!

With just the slightest bit of extra effort, that information could have been placed in the description field, where it belongs, but at least there is some non-ambiguous info on which driver is which.

So, I downloaded the bottom-most file from the list, and it turns out that what the table displays as this file's name actually is the file name, namely: "2007.10.31_Mac OS 10.5 PPD.hqx". If you stash that file away somewhere on your hard drive for later use, you may have a hard time to remember what, exactly, is inside, but, hey, it's got a useless date in an unusual format in it. How cool's that!

Double-click the file, and there's another surprise: inside the original BinHex file (obsolete Macintosh file format #1) there's a StuffIt archive (obsolete Macintosh file format #2) named "OS X 10.4 and 10.5 only.sit". Didn't the support site mention that this driver is for 10.5 only?

So what's inside that StuffIt file? Double-click the file -- after you've downloaded and installed StuffIt Expander if that utility wasn't installed on your Mac, yet -- and out comes a folder containing two installer packages, called "Kyocera OS X 10.4 v.1.0.mpkg" and "Kyocera OS X Japanese 10.4 v.1.0.mpkg." 10.4? What's with "10.5 only"? And why is there no reference anywhere to that v10.8 from the website's list?

On a quick side note, packing that folder containing the two installers with OS X's built-in Archive utility would not only have made it possible to open the file without having to install any third-party software. The resulting file size of 9.2MB would also have saved about 30% versus the 13.1MB of the file as offered by Kyocera. Ah well, never mind...

Double-clicked the installer file, read through the Read Me text in the installer, and, again, no mention of 10.5., as you can see in the screenshot to the right.

The installation as such went smoothly, though, and the installed driver works like a charm. Still, the overall experience was quite a bit of a mess and does make one wonder how much care they put into distributing their driver updates at Kyocera.

If you're a software developer, there are a few things to keep in mind when distributing software online so that your users will have a more enjoyable experience than I had:

• Make it easy to find the right file

  If you're just offering a handful of software products, putting a "Download X Now!" graphic on every page of your Web site is no big deal. If, however, you offer a multitude of software downloads, provide a well-designed, easy-to-browse list and/or -- even better -- add a search field in which the user can enter, say, the type of printer for which she needs an updated driver.

• When offering different versions, make it easy to see what each version is for

  This ties in directly with the first bullet above: for each version that you are offering, describe which version of the target OS, which version of the target application (for plug-ins), etc. it is for. E.g., in the case of the Kyocera drivers, there would have been no need to add that hidden-at-first information tooltip in the list of drivers if the OS version had been properly listed in each file's description field.

• Use meaningful file names

  Use a file name that will make sense -- to the user! -- even when looking at the file after a few months. E.g., instead of "2007.10.31_Mac OS 10.5 PPD" it would have been a lot more instructive to call that package, say, "Kyocera Printer Driver for Mac OS X 10.5".

• Use file formats that can be opened with on-board tools

  StuffIt and BinHex were extremely useful file formats back in the days of Mac OS 9. These days, though, OS X has built-in support for ZIP (and a number of other) archive file formats as well as disk images. Especially for any kind of try-before-you-buy software, requiring the (potential) users to install a third-party utility before they can install your software adds an extra hurdle to testing your products, which is unnecessary if you stick to file formats that OS X supports right out of the box.

  Obviously, the same applies to any other files in the package, too, e.g. manuals: include documentation files as PDF or plain text files, as not everyone has Microsoft Word installed on their Mac.

• Include a Read Me file

  If I'd get a Dollar for every software download that contains nothing but an application or an installer package...

  Displaying a Read Me file in the Installer is a good idea; including a Read Me file, and any further documentation required for using the software, in the disk image or ZIP archive is even better. That way, your (potential) users can read up on what your software does and which requirements it has without having to install or run it first.

  What needs to go in that Read Me file? More than ten years ago, Tonya Engst over at TidBITS wrote a triplet of articles on what makes a good Read Me file, and dispite their age, these articles are still valid, making them a very worthwhile must-read for any software developer.

Have I missed something in this list? What else would you expect from a decent software download? Also, if you have any software installation horror stories to tell, I'd love to hear those, too!