Better Distribution of Mac OS X Software

In the course of writing my current book, Mac OS X Power Tools, I downloaded, installed, and evaluated hundreds of pieces of software for Mac OS X: shareware, freeware, donationware, commercial software, you name it.

Besides finding a ton of cool software over the last seven months, I learned quite a bit about what developers do right - and wrong - when distributing their creations. Although many developers make the process of downloading, installing, and - when necessary - uninstalling software easy, at least as many don't. I'd like to provide feedback on this process from a user's point of view. It's worth noting that although some of my recommendations apply to any form of software, a number are aimed specifically at developers of Mac OS X programs.

<http://www.macosxpowertools.com/>

I wrote this article in the spirit of Tonya Engst's series of articles from the mid-1990s on "ReadMe" files - to provide suggestions for improving the user experience, and, consequently, help developers increase the use of and the purchase of their products. The good news is that these suggestions would take most developers almost no time to implement.

Before I discuss specific issues, I want to dispute an almost universal assumption that developers seem to make, perhaps unconsciously: that people install software immediately after downloading it. This one false assumption is, I believe, the primary reason why so many developers provide software the way they do. (You'll understand what I mean as you read the discussion that follows.) In my personal experience and in working with other users, it's in fact more common for downloaded software to sit on a computer for hours, days, or longer before anyone installs it.

That said, here are my observations and suggestions, divided into the categories of documentation, installation, distribution, and purchasing/registration. If you're not a developer, these suggestions may be more of an exercise in empathy than something that is directly helpful; however, if you agree with my comments, I encourage you to provide constructive feedback (with a link to this article!) to developers when you have similar experiences.

Documentation -- Yes, I know this is Macintosh software and the user shouldn't have to read the documentation. But even Apple's iApps, whose only documentation is relatively obvious online help, suffer from the lack of a manual, hence the popularity of books about the programs. Despite the continuing paucity of documentation these days (see Adam's "The Death of Documentation" article from five years ago in TidBITS-428), written assistance of some sort is important, and it will increase your users' comfort level and thus your number of purchases.

<http://db.tidbits.com/ getbits.acgi? tbart= 04865>

Always include a ReadMe file to describe your software. A disk image or StuffIt archive that contains only an application means that the user must launch the application just to find out what it does. More than once, I dumped software in the Trash rather than launching it and hoping it didn't do something irreversible. Placing the equivalent of a ReadMe file on your Web site isn't enough - some users may download from somewhere other than your Web site; others may download from your site, but get around to installing later and not recall the Web-based information.

ReadMe files should always include a URL to your Web site; not only is it helpful for the user, it's also good advertising. A ReadMe file's name should also include the name of your software; many users keep ReadMe files in a dedicated ReadMe folder, and having 100 files named "ReadMe" or "ReadMe First!" is terribly confusing. Finally, for additional tips about the content of your ReadMe files, check out Tonya's series on ReadMe files.

<http://db.tidbits.com/ getbits.acgi? tbser= 1039>

Think about the format for your ReadMe file and documentation. I don't recommend PDF files; they increase the size of your downloads, and both Preview and Acrobat Reader can be slow to load on some systems. If you use PDF, set the file attributes of your PDF files so that they'll open in Mac OS X's Preview instead of Acrobat Reader, since Preview is the default PDF/graphics viewer in Mac OS X. (Those who prefer Reader or the full version of Acrobat will most likely have configured their system to use it.) If you provide documentation in HTML format, use a file utility such as XRay to dissociate your HTML files from any particular browser. Doing so enables these files to be opened by the user's default browser when double-clicked; there are few things some users find more irritating than double-clicking an HTML file and watching Internet Explorer launch, even though Safari or Camino is the preferred browser. On a similar note, if you include an Internet Location file (essentially a link encapsulated in a file) with your software that lets the user quickly access your Web site, make sure it's a standard Mac OS X Internet Location file, and not an Internet Explorer "link." Many Mac users surf the Web with browsers other than Internet Explorer, and not all browsers can open Internet Explorer links.

<http://www.brockerhoff.net/ xray/>

If your application includes Help files, consider using standard HTML format rather than using Apple's Help Viewer. Help Viewer is a great idea and has the advantage of being able to download updates automatically, but the current implementation is slow, bloated, and buggy.

Lastly, whenever possible, I strongly recommend placing your Help files (along with an extra copy of the ReadMe) within the software's application package. When you do this, the user doesn't have to worry about installing, tracking, or updating any of these support files - installing a new version of your software package provides everything in one "file." If your product doesn't have its own interface - as is the case with preferences panes, plug-ins, background applications, and so on - consider including Help-like documentation in the ReadMe file or providing an Internet Location file in your download that links to online documentation.

Installation -- After finishing your documentation, pay attention to the installation process your users will experience.

Decide if you need to use an installer or if you can have the user simply copy your application package to the hard disk. The latter is easier, but doesn't give you as much control. That said, you can often eliminate the need for an installer by having your application (or even an AppleScript script stored inside your application package) perform necessary housekeeping on the initial launch.

No matter which installation method you choose, explain clearly how to install your software. This is necessary even if your software is just an application on a disk image; many users aren't familiar with disk images and don't understand that they need to copy files from the image to a hard disk. The trick of using a background graphic in the window to provide simple instructions works well. (Select icon view, choose Show View Options from the View menu, and then select "Picture" for the background.) Check out the disk image Karelia uses for Watson to see a good example.

<http://www.karelia.com/ watson/>

If your software uses an installer, state clearly - either in your documentation or on the first screen of the installer - exactly what will be installed, and where the files will live. Installers should always have an uninstall option that removes the software, including all support and preference files, but never user-created data, from the user's hard disk. Where that's not possible because of permissions or whatnot, or if you don't provide an installer, include instructions for uninstalling your software manually.

Finally, support Mac OS X's standard folder organization. Store preference files in ~/Library/Preferences (unless your software requires a system-wide license or preferences file, in which case it should go in /Library/Preferences). Other support files belong in ~/Library/Application Support or /Library/Application Support. Don't create new directories in ~/Library or /Library just for your application. Mac OS X's folder hierarchy may seem confusing at first, but that's only because it's so different from Mac OS 9. The more developers adhere to this organizational scheme, the easier it is for users to understand Mac OS X - consistency is the first step towards comprehension. In addition, it makes product support easier - if all programs adhere to Mac OS X's organizational design, users will start to learn where to look for particular types of files.

Distribution -- After figuring out your documentation and installation experience, turn your attention to distributing your software.

Above all else, make sure your download works; in other words, that it downloads as a complete file to the user's computer. Most users don't know what to do if clicking a download link results in a browser window full of code. Test all your download links in several different browsers to make sure they're handled properly. (Many developers provide links to multiple sites, such as VersionTracker, MacUpdate, or Info-Mac, in an effort to reduce bandwidth load.)

If you distribute your software using Mac OS X's disk image format, make sure your disk image actually mounts. I was unable to evaluate several products because of corrupt disk images.

Make sure to give the file you're distributing - whether it's a disk image, a StuffIt archive, or any other format - a meaningful name that includes the software's version number. Users who see a file called "jcc.dmg" probably won't recall what they downloaded. Further, some users keep downloaded files around in case they need to reinstall, or for installing on multiple computers, so a meaningful name with a version number helps them organize their collections of downloaded files. Also, including the version number in the archive's name is helpful for the Info-Mac archivists if you submit your software there.

<http://www.info- mac.org/ how/ submit.html>

Although you should include the version number of your software in the image or archive name, you should never include that version number in the name of the application itself. By keeping the application name constant across versions, users can upgrade by simply overwriting the previous version with a new version. If you include the version number in the name of the application, many Mac OS X features - such as double-clicking documents or launching via Login Items - may not work as expected after an upgrade, since Mac OS X often looks for applications by name (as opposed to Mac OS 9 creator codes). Put the version number where it belongs - in the version string inside the application - so that users can find it in the application's Get Info window.

I'm not going to weigh in on the whole StuffIt archive versus disk image debate; both have their merits and faults. In addition, Apple's newest type of disk image, "Internet-Enabled," (which, oddly, is not "enabled" in any way that remotely relates to the Internet) is gaining popularity. With an Internet-Enabled disk image, the user downloads the disk image; the browser automatically opens the downloaded file with Disk Copy; and Disk Copy mounts the image, copies the contents out of the image, dismounts the image, and moves the disk image file to the Trash. (Users can extract the disk image from the Trash if they want to save it for additional installations.) Some people dislike Internet-Enabled disk images because they initially seem confusing. However, their behavior is actually quite familiar if you think of them as a disk image approximation of a StuffIt archive - double-clicking an image results in the contents of the image replacing the image itself, assuming a copy of StuffIt Expander set to delete intermediate files.

<http://developer.apple.com/ ue/ files/ iedi.html>

Purchase/Registration -- Assuming that you've created the next killer app, you don't want to mess up your chances for wealth and fame with an incomprehensible purchasing or registration process.

Make your software easy to buy! If it's available in stores, tell users which stores. If it's available from major Web retailers, link to product pages on those sites. If you distribute it online yourself, provide an easy way to pay, such as Kagi, eSellerate, or one of the other payment processing services. There's nothing wrong with using PayPal, but I don't recommend relying on it as your only, or even primary, payment service; many people dislike PayPal and you may lose a paying customer simply because you don't offer an alternative payment method. (This goes both ways - every service has dissatisfied customers; the more options for payment you provide, the more likely someone will find one they're willing to use to buy your product.) Make your purchasing processing friendly to international users whenever possible; after all, nearly half of all Macs are sold outside the United States.

<http://www.kagi.com/>
<http://www.esellerate.net/>
<https://www.paypal.com/>

Don't worry about the seemingly high processing fees of these services; users are comfortable with paying through Kagi and the others, and making users comfortable translates directly into them paying for software more frequently. So although using a payment service may mean less profit per transaction, overall you'll surely come out ahead. Most likely far ahead.

Successful Distribution -- You put a lot of work into your software, so don't undermine it by making unnecessary mistakes when distributing it to the world. Each suggestion in this article may have seemed minor, but a series of minor gripes can result in major inconveniences for your users. Considering that developers need users to enjoy their experiences with software products, it follows that they can increase the chances of such enjoyment by making the most difficult parts of the process for most users - acquisition, installation, and purchasing - as simple and problem-free as possible.

[Dan Frakes recently finished writing Mac OS X Power Tools (appearing soon from Sybex) and is finally getting some sleep.]

<http://www.danfrakes.com/>

Reprinted with permission from TidBITS#678/28-Apr-03. TidBITS has offered more than ten years of thoughtful commentary on Macintosh and Internet topics. For free email subscriptions and access to the entire TidBITS archive, visit www.tidbits.com.