Tips & Hints for
Shareware/Freeware Authors

Written by Matthias Kahlert, mkahlert@kagi.com
http://www.GeoCities.com/SiliconValley/Pines/8031/index.htm

General Information: Writing Good Documentations

Every good shareware or freeware application needs a good documentation. Even if your software is self explanatory or constists of just one single dialog window you should include a Read Me file that explains the basic things of your program.

Here are some ideas for the fundamental parts of every good documentation:

Author Information

The most important part of every documentation is the part about yourself. And this should consist of:

You should include all possible information about how to contact you, the author.

Always think about that: Something distributed to the Internet will never disappear. So if you put something on any server in the World Wide Web, you can be sure that it is still somewhere many years later.
So if you moved during that time and if you told the people to send you a postcard, it may be difficult for them to find out your new address.
So if possible you should try to get a Post Office (P.O.) Box and/or an e-mail and URL forwarder. Keep your contact addresses as abstract as possible, so that a part of them is still valid after some years.

What does your Software do?

Do not forget to write something about what your software does. You should start your documentation with a short summary about the main functionality of your application.

What does it do? Or better: What can the user do with it? Who is the target group of your application? Who can use your application? Does the user need any previous knowledge?

System Requirements

Include a short summary about the minimum and the recommended system requirements. Is there any special hardware needed? Does your application also run under older operating system versions? How much memory does it need?

Registration Information

Another important part of your documentation is a section about registrations. You should make clear what kind of software it is (Freeware, Shareware, Postcardware, etc.), what it costs and how the money has to be transfered to you.

If your application is shareware you should include detailed information about what the user has to do. Especially if you use a payment service like Kagi Shareware you should inform the user about the different available payment methods (cash, check, money order, credit card, etc.), where he has to send the money to, etc. And don't forget to tell the user how long the payment process will approximatly last.

Installation

Let the user know how to install your application. Is there a setup application or installer included, or does the user have to install it "by hand"? What about an Uninstaller?

Many users will also be grateful if you tell them where the files are installed. This is important especially for Windows applications. It's always hard for the user to completely uninstall your software if the Uninstaller doesn't work correctly.

Version History

You should also include some information about the current and the previous versions of your program. Don't forget to include the release date of the current version, so that the user can find out how old his version is.

More Information

If you just wrote a short Read Me file let the user know where he can get further information (for example al list of Frequently Asked Questions, the Online Documentation, Mailing Lists, etc.) or how to contact you, the author.

Quick Start

Every good documentation contains a QuickStart section. In this section you can explain the basic elements of your application. Just describe the shortest possible way that brings the user to any output or goal.

Frequently Asked Questions

Especially in more complex applications you should consider to include a FAQ (Frequently Asked Questions) section. A FAQ page can save you a lot of time, because people often don't read the manual, but they seem less reluctant to read the FAQ. This can save you a lot of time when you answer the most questions before the user contacts you.

Annotations

If you have any annotations about how to write a good documentation, please let me know. Just send an e-mail to mkahlert@kagi.com.

Modified on 6. June 1997

Back