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

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