AddThis Social Bookmark Button

Listen Print Discuss
Mac OS X > Excerpts >

The Do's and Don'ts of Shareware, Part 2
Pages: 1, 2, 3

Anatomy of the ReadMe File

A great place to learn about ReadMe files is to read some. No kidding. You'll find all sorts of variety, from one-liners to entire rolls of toilet paper. Some never end. (This article may never end.)



Here are some sections users will like to see in a ReadMe file:

DO format your readme file so users can easily find the information they're looking for.
  • The name of the software.
  • The name of your company.
  • The URL for your company, double-clickable if possible.
  • A brief description of what the software does.
  • Contact information for support. (Email, address, phone, etc.)
  • A list of what files are present in the archive and what they do.
  • Instructions on how to register.
  • The cost of the product.
  • Installation AND uninstallation procedures.
  • Are you reading this?
  • Basic instructions on how to use the software.
  • A change log back through the first version of the software. (A surprising number of users like to see these details.)
  • A legal disclaimer.

Keep in mind that MacOS X TextEdit.app can open SimpleText read-only files (type 'ttro') without having to launch Classic.

Another great format for ReadMe files is html. The problem with this on MacOS 9 or before is the user may not have the browser installed for the creator of the html readme. So the user can double-click the file and get an error. On MacOS X, since creators are not necessary, this is not a problem.

You may consider hosting your documentation on your Web site.  Making last-minute corrections is impossible when your documentation is already installed on a user's machine.  Also, many users like their documentation in printable form.  For this, PDF is ideal.

Creating Your Sales Venue (Web site)

Marketing is always fun. The best part about it is that you can turn for marketing to the same place that you turn to for cheap car insurance, competing mortgage companies, and Foam Bath Fish Time: the Internet.

Don't panic. There's no rule that says your Web site needs to have 50 cross-referenced pages, or animated gifs of cartoon characters using your software (although that would be pretty cool, wouldn't it?). The basic idea of creating a Web site from scratch is the same idea as creating a 1.0 release of a piece of shareware: keep it simple, silly. A Web site, like a piece of software, can evolve as new needs arise, and can change very quickly in response to user feedback. Think of it as a piece of clay that never hardens. If you don't get it right initially, you can always mold it into something better later.

Another good reason to keep the Web site simple at first is that you won't have extraneous information users won't want. Only add sections or information users ask for. Only then will your Web site do what it's supposed to: help your users find things quickly so they can get on with their lives.

Basic Sections

Below are four basic sections users will expect to see on a shareware Web site:

  • Home: From Home, link to all other areas and products.
  • Support: Support pages should include E-mail contacts and perhaps Frequently Asked and Answered Questions.
  • Purchase: Instructions and links to your Web store. (To be described later.)
  • Products: Description information and download links for individual products. Descriptions of products should be no longer than two sentences.

Beyond these three sections, what you add is up to you. As a shareware developer, if you receive a lot of emails asking about who you are, add an "about" section. Don't be shy. Your Web site should evolve similarly in response to frequent user feedback on any given issue.

As you design your Web site, be sure links are visible and in obvious places. Users can't read your mind. (No, they really can't.)

There's no one right way to do a Web site just as there's no one way to design a storefront. Drive around your neighborhood and you'll see hundreds of unique storefronts competing for your business. There are no limits to what you can do with your Web site.

DO remember that there's no one perfect way to format your Web site. The overall look and feel of your site will depend mostly upon your own tastes.

DO shop around. There are some great examples of Web sites out there.

DON'T clutter your Web site with extraneous information.

Tools to Help

Use as many tools as possible to help you manage your Web site. Relative links are a pain to get right, but tools like Bare Bone's BBEdit software make it easy. Same goes for importing common elements into your entire site with one click of a button. The tools are available so you might as well use them and save yourself the headache.

Graphics

If you're not very good with graphics, find a local artist to help you out. A local artist usually costs between $20 and $60 per hour, and if you're completely devoid of any artistic talent (like most people), you might want to give outsourcing a try.

Small screen shots of your software in action will also quickly and easily help potential users understand what the software does. Sometimes a picture is worth a thousand words. (We don't have a whole lot of original sayings here.)

ISP

You'll want some pretty serious power from your ISP. There are thousands of ISPs out there, all with many features. Most decent Web hosting ISPs cost anywhere between $15 and $45 per month, and sometimes charge a set-up fee. Here are some features you will want from your ISP:

  • A good track record. Find one that a friend recommends.

  • FTP access to your domain's home directory so you can upload your Web site easily.

  • Perl scripting with sendmail. This is really important if you want to create a Web form and be emailed the results.

  • Multiple email addresses with forwarding or one email address with lots of aliases. Create separate email addresses for press releases, support, and sales. That way you'll be able to filter incoming messages for better organization.

  • An ISP that's willing to configure MIME types. When a server sends a Stuffit archive to a user's browser, the server sends along a MIME type. There are specific MIME types for specific types of Macintosh files, and these are not always enabled by default.

  • Relatively high disk space. A typical shareware company's Web site may fill up to 50 MB of disk space. When calculating necessary size, don't forget to consider the sizes of archives, localized versions of those same archives, and graphics. Also remember that no one person will ever download all of it. So disk space isn't necessarily proportional to the time required for your pages to load.

  • Backups, Uninterruptable Power Supplies (in case of brown outs), and redundant links to the Internet.

  • If you're planning on doing a lot of scripting, you might want an ISP that can handle PHP and MySQL.

A good and friendly ISP is Pulver Technologies. Their uptime is excellent, and they repair inevitable problems quickly. Although once you sign up, Pulver Technologies is pretty much self serve.

Web Forms

DO create a Web form to collect customer's email addresses so they can learn about new products and updates.

DO create a Web form as a way for your users to change their address in your database.

DO remember that simple Web form back ends will email you the data field values in a special format. This is typically called a "formmail cgi", and is supported by most ISPs.

DON'T violate your user's privacy.

It's quite surprising how many users want to be kept informed about new products and updates. Provide a simple Web form to collect this information. It's free, easy, and gives you a list of people who actually want to learn about your goods.

A great marketing tool is to find out from users how they heard about you. Then you know where your users are going for information, and you can be sure to send future press releases to those who made the referrals.(But only if they want it, right?)

Privacy

The idea of Web forms brings us to our next quick topic: privacy. Don't sell your mailing lists or give them away. You'll only upset your users. Plus, you'd be surprised to learn how many users use custom email addresses so they know who they've given their address to. Because of this, if their particular email address is ever used for spam, they'll be able to track it back to you. And that's not a good thing.

So write a privacy statement, and forget about ever giving away any personal information. This policy is better for everybody.

Distribution

Below are a few notes on actually distributing your software.

By Download

Offer two or more mirror locations from which users can download your software. We are, after all, dealing with the Internet here. Servers fail. And so do links.

Download Size

Remember that users need to download your archives.  It's a good idea to make sure your archives aren't larger than an average user can download from a dial-up ISP in 20 minutes.  Large archives are often skipped by users entirely.

Registration Numbers

DO keep registration numbers short.

DO only use digits.

DO only use one bit in your registration code for binary fields.

DO be careful of unicode characters on foreign systems. They'll appear in fields whether you know it or not.

DO be sure you can write your registration code in languages other than C or C++.

DON'T forget to test your code.

When shareware is actually sold, what's transferred from the company to the user is a registration number. This is usually done by email only. Using a predefined mechanism, the users enter the registration numbers into their software thereby extending the software's lifetime indefinitely. Registration numbers can be generated on-the-fly by the company handling your sales. (See next installment.) But from a programmatic point of view, there are a number of values shareware developers may want to mathematically incorporate into their registration scheme:

  • A sequential and unique serial number.
  • The quantity of products purchased.
  • A special code identifying the product purchased.
  • A checksum of the user's name or organization.
  • A checksum for the registration number string itself.
  • A release version.
  • Operating system flag and version. (i.e.: If the Mac and Palm registration numbers for a piece of software do not cross-pollinate.)
  • A random number to throw off naive crackers, sometimes called "salt" in encryption circles.

  • A code generation date.
  • Expiration information.
  • Sales engine code.
  • A code to identify the referrer.  (Sometimes customers will be referred to your sales site by a third party.)

There are a number of hidden gotchas here. Don't forget that on foreign language systems, usernames and organizations may be unicode. Also, avoiding letters in the supplied registration code altogether will reduce the number of support emails. Users are easily confused, and rightly so, by lower case "L" characters, upper case "i" characters, and the number one. Same holds true for zero. Using only digits nips this problem at the bud.

Ambrosia Software's 'fprefect' wrote an excellent article detailing an expiring registration number scheme.

Wrap-up

We covered a lot of ground today. The general idea behind creation of the software, the Web site, and the entire sales experience is to keep it simple. Lone developers have no choice. Don't feel overwhelmed. Most of the items are completely optional. And many of the items are personal preference.

Next time we'll be wrapping up the series with a discussion of press release format, sales transactions, user support, a checklist for launch, a few notes about localization, and what you need to work from the road.

Sanford Selznick is the owner of Selznick Scientific Software, LLC, a programming, consulting, and shareware company based in Tucson, Arizona.

Read more Developing for Mac OS X columns.

Return to the Mac DevCenter.