Re: [GENERAL] Is my MySQL Gaining ?

On Monday 29 December 2003 12:47, Tom Lane wrote:
> Shridhar Daithankar <shridhar_daithankar(at)myrealbox(dot)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