I was reading the QMail wiki and came across a project called Qmail Toaster. I thought "ooh... that looks interesting" and wondered what it is. The QMail wiki page doesn't say anything about what the project is for or what problem it solves. It just tells you to read the following web sites:

1. Qmailtoaster home
2. Qmailtoaster documentation wiki
3. Qmailtoaster Plus project page
4. Video tutorials

The Qmailtoaster home page is basically a list of features presented in no particular order. The Qmailtoaster documentation wiki's introduction and history page just goes on about how easy it is to install even for an inexperienced user. The Qmailtoaster Plus project page says it's an extension to Qmailtoaster - whoopy - we're still not getting anywhere! I pinned all my hope on the Video tutorials but the site is down.

I read around the web sites and after 10 minutes, I was still none the wiser as to what the project was actually for and what job it did inside QMail.

Hunted around a little bit more and found out that "QmailToaster-Plus is an RPM package that contains a menu and supporting scripts which add additional features and utilities to your QmailToaster" - great so what is QmailToaster?

Another page says "Miguel's goals were to provide a very stable rpm based Qmail MTA" - ok now we are getting somewhere. So what is a "Qmail MTA" and how does that fit into QMail?

I don't mean to be so flippant, but it took 10 minutes to find out what this project is actually for once I had got passed all the easy-to-use, rpm-packed, more-features-than-you-can-shake-a-stick-at style adverbs.

It constantly surprises me how many projects miss this out and think we can deduce what the project is for by reading a stream of features.

I'm not psychic, and I don't want to spend ages hunting around for answers. Documentation comes in 2 parts. The first part is essential: what is the project for, and the second is optional: how do you use it. The second part maybe deduced by reading source code or forums and so can be omitted. Once you've seen enough open source projects you will realise that how-to-use documentation is a luxury but you can get by without it. Whereas the 1 or 2 sentences that open a project are the most important. They tell you whether or not you need the project. If you don't then you can stop reading straight away and move on to the next project.

Some guidelines

Here are some guidelines to help you with defining your project.

1. Give the section its proper title - The best example of this is a section header called "What is Blar". Most people who are looking for information will sooner or later end up at Google's front door and they are going to type "What is Blar?". Do you want them to be given a link to the front page because Google can't actually tell you what it is, or would you like a link taking you to the section of the documentation which describes what Blar is? Do you want the punter's question to be answered straight away or do you want them to have to hunt around your web site trying to figure it out; all the while wondering why Google didn't display the "What is Blar" page!
2. Have a proper start to the What-Is section - Your What-Is section should start in the standard format beginning with "Blar is a ...". Once you have said what it is (in one sentence), you can follow it up with another sentence to say what it might be used for or what problem it solves.
3. Don't use acronyms - Every time you use an acronym you are giving the reader a chance to leave because they have to go away and look up the acronym. You could argue that if the reader doesn't understand what JPA stands for then they have no business reading your documentation, but you will find that in every given area (especially in computing) about 75% of your readers will be beginners. If they were experts they probably wouldn't be looking for help in your documentation!
4. Don't use jargon - This is the section of your documentation that users are going to read first. They are going to use the outline drawn up from this section to base all their subsequent research on, so make it simple. Anyone should be able to read your What-Is section and know if it is something they would like to invest their time in.
5. Keep it short - If you can't condense your project down into a couple of sentences how are you going to organise your real documentation.
6. Don't reuse words from your project name to describe the project - A nice example of this is "A toaster toasts your bread" - hurray! If I don't understand the concept of toasting then I'm not going to get anywhere.

Examples

Here are a couple of examples to describe what I'm getting at.

1. What is a Toaster? One sentence that really says it all.

   "A Toaster is a device for cooking bread."

2. What is Apache Camel? Only 2 sentences. Even a brick layer or an accountant could have an idea about what this project does:- something about writing industry plugin'able standards.

   "Apache Camel is a rule-based routing and mediation engine which provides a Java object based implementation of the Enterprise Integration Patterns using an API (or declarative Java Domain Specific Language) to configure routing and mediation rules. The domain specific language means that Apache Camel can support type-safe smart completion of routing rules in your IDE using regular Java code without huge amounts of XML configuration files; though XML configuration inside Spring is also supported."

3. What is MantisBT? The first part of the first sentence outlines what the project is, then follows a brief elaboration. Still only 3 sentences, but it tells you everything you need to know to decide if you want it or could use it.

   "MantisBT is a web based bug tracking system that was first made available to the public in November 2000. Over time it has matured and gained a lot of popularity, and now it has become one of the most popular open source bug tracking systems. MantisBT is developed in PHP, with support to multiple database backends including MySQL, MS SQL, PostgreSQL and DB2."

I wrote to the project lead of QMailToaster explaining to him how difficult I found it to figure out what his project was for. So just to show there is no hard feelings here's their new version. It still needs a bit of work (IMO) but it's a start, "What is QMailToaster?"

"QmailToaster is a full blown mail server distribution for use with most rpm based Linux distributions. QmailToaster is distributed as source rpm's which require compiling on the host system before installation. This is done to meet licensing requirements set forth by the original creator of qmail, D. J. Bernstein."