Documentation

• Previous message: Dieter Bender: "Re: simple max function?"
• Next in thread: David Harper: "Re: Documentation"
• Reply: David Harper: "Re: Documentation"
• Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]

Date: Sun, 20 Jun 2004 02:30:38 GMT

I am rather amazed at the quality of documentation of MySQL and
HSQLDB. I would think given the extreme competition in this area, that
the documentation on the popular databases would be first class.

Yet it is abominable. You could easily waste 2 days just getting
HelloWorld to work.

You need two kinds of documentation:

1. getting started. Which leads you step by step through a simple
project, such as HelloWorld.

2. reference docs.

The most popular model of documentation seems to be the FAQ where the
questions surely cannot be Frequent given how esoteric they are and
there is no order, just a giant heap. Every triviality is treated
identically to the set of 10 questions every newbie must answer to be
able to even get started.

The readme file never tells you where to get started. They just talk
about changes to the products internals which is of no interest to a
first time user and of little interest to anyone else.

Most of the reference documentation is irrelevant to most of the
users. There needs to be a way of classifying facts by how important
they are, and providing some sort of automatic filtering to avoid
overwhelming the reader with stuff he already knows, or with stuff
that is unlikely to be useful.

I suggest how to proceed at http://mindprod.com/jgloss/author.html

-- 
Canadian Mind Products, Roedy Green.
Coaching, problem solving, economical contract programming. 
See http://mindprod.com/jgloss/jgloss.html for The Java Glossary.

• Previous message: Dieter Bender: "Re: simple max function?"
• Next in thread: David Harper: "Re: Documentation"
• Reply: David Harper: "Re: Documentation"
• Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]