- 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!
- 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.
- 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!
- 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.
- 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.
- 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.
“A Toaster is a device for cooking bread.”One sentence that really says it all. 2. What is Apache Camel?
“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.”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. 3. What is MantisBT?
“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.”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. 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.”
Comment from: Nisar Ahmed [Visitor]
Comment from: josef betancourt [Visitor]
Comment from: E.R. [Visitor]
Comment from: jp [Visitor]
Comment from: jm [Visitor]
Comment from: [Member]
That page (also included in the blog entry) just says it’s a mail server and then it spends the rest of the description babbling on about the fact it supports RPMs! Most distributions do anyway so there is no differentiation here!
If it’s just a mail server, why don’t I just use Sendmail? Or Qmail? From the description, what makes this project worth switching over to? Nothing!
Comment from: Ed Graham [Visitor]
I agree entirely, although I think your answer on Stack Overflow regarding Apache Camel was much clearer than the one you gave here:
Form is loading...