Re: Is my MySQL Gaining ? - Mailing list pgsql-general

From Tony
Subject Re: Is my MySQL Gaining ?
Date
Msg-id 3FEFEF82.7080305@unihost.net
Whole thread Raw
In response to Re: Is my MySQL Gaining ?  (Shridhar Daithankar <shridhar_daithankar@myrealbox.com>)
Responses Re: Is my MySQL Gaining ?  (Shridhar Daithankar <shridhar_daithankar@myrealbox.com>)
Re: Is my MySQL Gaining ?  (Tom Lane <tgl@sss.pgh.pa.us>)
List pgsql-general
I agree with you (speaking as a newbie) I don't believe any dumbing down is necessary at all.  I DO believe however that a decent introduction to the more important concepts (Triggers, Fkeys, Stored Proc, Views) that people from lesser systems (MySQL, Access) may not be familiar with. What they do, how they help, and why they are generally a good thing.  This intro would probably fit either in the tutorial or in the User Guide.

Don't hold peoples hand for them, but at least provide them with the tools they need to make an educated decision.

T.

Shridhar Daithankar wrote:
On Monday 29 December 2003 12:47, Tom Lane wrote: 
Shridhar Daithankar <shridhar_daithankar@myrealbox.com> writes:   
That is right. but that fact remains that postgresql documentation is
just sufficient. If you read the manual and follow it religously to comma
and fullstop, it tells you everythings. But it certainly isn't a place
where you can glance over it and get hang of it.     
This is surely true, and I've not seen anyone denying it.  The people   
Well, for newbies to postgresql, let's state this fact upfront and not make 
them discover it..:-)
 
who are doing development are, um, not strong at documentation (I
include myself here).  What we need are some folks to step up and
improve the documentation --- and then maintain it in the face of future
changes.  Any volunteers out there?  This is an open-source project
after all, and that means "scratch your own itch" among other things...   
If you ask me, let's not do that. Not at least on a grand scale. Isolated 
areas are OK on case by case basis..

I regualrly use development build documentation from developers.postgresql.org 
and I have seen the documentation in source code. In my view, postgresql 
developers do document it very clearly whenever required.

If we dilute the documentation too much, that will make things simpler 
initially but that will simply create a maintainance nightmare as one has to 
maintain much larger amount of documentation.

And once you get used to precise style of postgresql documentation, going back 
to anything else is a pain. ( MSDN.. I scream at nights.... but I digress).

IMO documentation of postgresql is fine overall. What we need to do is.

1. State upfront that this is not handholding. 

It will make lots of things easier and offload work of expanding documents 
given limited human resources working on the project. A disclaimer is far 
easier to maintain than a manual..:-)

And it will prepare anybody for upcoming hardships..:-)

2. Document and reuse it.

Personally I would like to see responses on general and oter such list as 
URLs. If we answer it repeatedly, let's document it and point the people to 
them. Let them dig around 3-4 URLs around it and they will have islands of 
enlightenments. Over the period, these island will merge in a great 
landscape..:-)

Just a thought..
Shridhar

P.S. If somebody thinks I can not imagine how a newbie feels, I will agree. 
But looking back, dumbing down anything is not good in long term..an 
experience that is


---------------------------(end of broadcast)---------------------------
TIP 1: subscribe and unsubscribe commands go to majordomo@postgresql.org 

pgsql-general by date:

Previous
From: Gaetano Mendola
Date:
Subject: Re: Is my MySQL Gaining ?
Next
From: Shridhar Daithankar
Date:
Subject: Re: Is my MySQL Gaining ?