Quoting Shridhar Daithankar <[EMAIL PROTECTED]>: > On Monday 29 December 2003 12:47, Tom Lane wrote: > > Shridhar Daithankar <[EMAIL PROTECTED]> 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 [EMAIL PROTECTED] >
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 ---------------------------(end of broadcast)--------------------------- TIP 3: if posting/reading through Usenet, please send an appropriate subscribe-nomail command to [EMAIL PROTECTED] so that your message can get through to the mailing list cleanly