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

Quoting Shridhar Daithankar <shridhar_daithankar@myrealbox.com>:

> 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
>

Shridhar,

I tend to agree with you.  I personally think the docs are very good and have
the techical depth warranted for a product like PostgreSQL.  On the other hand
for the ad & m (advocacy and marketing) side of things.  I'm betting some
clearly labelled tutorials/guide next to the disclaimer about the the main docs
be more of a reference would appease those who might be a bit green to a product
of PG breadth and depth (heck I still think I'm in the category sometimes).

'bout two weeks ago there was another thread where certificating/training et al
were discussed and one of the things that I had mentioned was that in that
regard, we should probably have more tutorial/guide based on real world
scenarios available on techdocs.  Although I don't think I qualified to write
for the main docs, I definitely can contribute to the techdocs in the manner I
just mentioned.

Matter a fact, I finally finish my first one "Using PostgreSQL for Domino 6
RDBMS Backends".  I'm doing the final read now so hopefully I can get it over to
Robert for posting.

Perhaps the "newer" folks on the list could tell us what type of guides they
want to see.  I'm sure someone has a wish list somewhere.

--
Keith C. Perry, MS E.E.
Director of Networks & Applications
VCSN, Inc.
http://vcsn.com

____________________________________
This email account is being host by:
VCSN, Inc : http://vcsn.com