Received: from maia.hub.org (maia-2.hub.org [200.46.204.251]) by mail.postgresql.org (Postfix) with ESMTP id EA9C71337BA6 for ; Wed, 9 Mar 2011 21:43:29 -0400 (AST) Received: from mail.postgresql.org ([200.46.204.86]) by maia.hub.org (mx1.hub.org [200.46.204.251]) (amavisd-maia, port 10024) with ESMTP id 87777-06 for ; Thu, 10 Mar 2011 01:43:22 +0000 (UTC) X-Greylist: domain auto-whitelisted by SQLgrey-1.7.6 Received: from nm20-vm0.bullet.mail.ne1.yahoo.com (nm20-vm0.bullet.mail.ne1.yahoo.com [98.138.91.45]) by mail.postgresql.org (Postfix) with SMTP id A431D1337B69 for ; Wed, 9 Mar 2011 21:43:21 -0400 (AST) Received: from [98.138.90.48] by nm20.bullet.mail.ne1.yahoo.com with NNFMP; 10 Mar 2011 01:43:20 -0000 Received: from [98.138.89.174] by tm1.bullet.mail.ne1.yahoo.com with NNFMP; 10 Mar 2011 01:43:20 -0000 Received: from [127.0.0.1] by omp1030.mail.ne1.yahoo.com with NNFMP; 10 Mar 2011 01:43:20 -0000 X-Yahoo-Newman-Property: ymail-3 X-Yahoo-Newman-Id: 785677.6681.bm@omp1030.mail.ne1.yahoo.com Received: (qmail 93363 invoked by uid 60001); 10 Mar 2011 01:43:20 -0000 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=yahoo.com; s=s1024; t=1299721400; bh=e93NyTZJeOzZBSwx/fYYegeBACcb8Lw7iwAuP0ygNEA=; h=Message-ID:X-YMail-OSG:Received:X-Mailer:Date:From:Subject:To:In-Reply-To:MIME-Version:Content-Type; b=lUJY4G01p1wroHG5bZ82hZYUyPXXuUKPshP+LCIVIp+3//EcU1PY1z/+dtru+sQu4PnPkOXD1xxAgySj/zbkadUtwG1Z4GpCg/j9onQNS9uK8YnWLQrmW3aZjZBA3HCd+buhtCb7oXPTDHa9UfCxdQWcQxI+Brq3KBo9nyq4Be4= DomainKey-Signature: a=rsa-sha1; q=dns; c=nofws; s=s1024; d=yahoo.com; h=Message-ID:X-YMail-OSG:Received:X-Mailer:Date:From:Subject:To:In-Reply-To:MIME-Version:Content-Type; b=dbxse/oHerbA3iMNK8GtRmfBA8fiIEy4LDkwvB6N0teXQ/8ZzOe1TEIPFyLAdBEBBlUFHML5fof2WTIUiZNC262W2pNIC40+QDa6p88LjoYMhhRMlRopxVueF6RnG/cUp3Gpz4qv5xNJOVZbstFRj9qmzyNmCDtcmJyDBDMt7Nc=; Message-ID: <59974.87985.qm@web110707.mail.gq1.yahoo.com> X-YMail-OSG: KOpuFKsVM1kv.Zk_9VX1sD8kG.ziOJpGRFp1pCPim58Epqq RX1oqU6atWU_H2UtHEA1xClq6I2Tp.0N.pUDpoxaZnX51qdQYbLpqJNs6r0z C0_ZBcOfK_yRPd6aBfDO1gbPbqy2m6nu8_au47G8biBMBwTeDoU88MznqiM_ xXEVM57RW1fNytaObZ4IYqhNuYjVzklcNQ1UiRU2Z18U_z441oTBnpAETlBr 7gNi3Fk5ImY_ZtinI2K5fzMKUpOkoKi0z_d3UAEcNlWtH2CzS5SmPvBIm7lm viF5O9Z86YMvNLaPl51OFj1cwiNBlwFubJqNo0VFBxFUUCirH_SGa2l_EtfS VNB0TCWxXgHFR__jrCtkfkGQ24awybe4Cc7t8dp5ZBJBb7D3gfnsKJcLqXoG bPAAMFDrR01c- Received: from [70.49.69.102] by web110707.mail.gq1.yahoo.com via HTTP; Wed, 09 Mar 2011 17:43:19 PST X-Mailer: YahooMailClassic/11.4.20 YahooMailWebService/0.8.109.295617 Date: Wed, 9 Mar 2011 17:43:19 -0800 (PST) From: Leslie S Satenstein Subject: Improve initdb and pg_controldata manual pages To: PostgreSQL-documentation In-Reply-To: MIME-Version: 1.0 Content-Type: multipart/alternative; boundary="0-939785561-1299721399=:87985" X-Virus-Scanned: Maia Mailguard 1.0.1 X-Spam-Status: No, hits=-0.507 tagged_above=-5 required=5 tests=BAYES_05=-0.5, FREEMAIL_FROM=0.001, HTML_MESSAGE=0.001, RCVD_IN_DNSWL_NONE=-0.0001, RFC_ABUSE_POST=0.001, T_RP_MATCHES_RCVD=-0.01 X-Spam-Level: X-Archive-Number: 201103/55 X-Sequence-Number: 6488 --0-939785561-1299721399=:87985 Content-Type: text/plain; charset=iso-8859-1 Content-Transfer-Encoding: quoted-printable On Wed, 3/9/11, Robert Haas wrote: From: Robert Haas Subject: Re: [DOCS] Improve initdb and pg_controldata manual pages To: "Bruce Momjian" Cc: "Tom Lane" , "PostgreSQL-documentation" Date: Wednesday, March 9, 2011, 12:21 PM On Wed, Mar 9, 2011 at 11:08 AM, Bruce Momjian wrote: >> Hard to say. =A0We have the problem that our docs were made by a lot of >> people over a long period of time, so inconsistencies are a fact of >> life. =A0"Pro" documentation might be more consistent if it's written by= a >> smaller group of people over a shorter period of time... > > We probably have higher quality but lower consistency. Isn't consistency part of quality?=A0 I think on the whole that our docs are excellent in both quality and consistency.=A0 There are things that I'm not happy about, but this particular issue seems like the sort of thing that's not really worth spending effort on.=A0 I think the portions of our docs that could still use some work are the newer portions, such as the Hot Standby docs, which still feel a little rough compared to some other places - sort of a laundry list of things that will and won't work (UUID generators?).=A0 I'd rather see us invest time in general copy editing than spend a lot of time creating an unnecessary and possibly confusing consistency with regards to something like this. --=20 Robert Haas EnterpriseDB: http://www.enterprisedb.com The Enterprise PostgreSQL Company --=20 Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs I have to agree with Bruce M. that the docs are in need of some work. I thi= nk there are two or more viewpoints. =0A =0AThe docs should contain the detailed information concerning postgresql f= unctions, with no omissions. =0A =0AThe docs should be well formatted so that the PDF files created are clea= r and understandable. =0A =0AThe docs need consistency, so that the information therein is not=0Amisc= onstrued by an English speaking / reading non-American.=A0 The=0Adocumentat= ion has many many grammar mistakes, where pronouns refer back=0Ato more tha= n one noun, or adverbs refer to more than one verb.=A0 I found=0Athe author= s mean very well, but they mix usage based on programming=0Athoughts.=A0=A0= Fields give, instead of contains, is one example.=A0 Here is=0Aa context t= o illustrate. =0A =0AThe function xyz() has two variables. A list of keywords, and a list of= =0Avalues which gives results.=A0 Now the value variable actually contain= =0Avalues associated with keywords, and together these are the functions=0A= input parameters. The function does not work with keywords alone and=0Athe = result gives the values.=A0=20 =0A =0AConsider this example as typical of what I forwarded to Bruce M. a while= back. =A0 Some people have ebook readers and do want to read the PDF versi= on of the docs via their ebook readers. =0A ------------------ p.MsoNormal, li.MsoNormal, div.MsoNormal { margin: 0in 0in 0.0001pt; font-s= ize: 12pt; font-family: "Times New Roman"; }filtered { margin: 1in 1.25in; = }div.Section1 { }Regards =20 =A0Leslie Mr. Leslie Satenstein 40 years in IT and going strong. Yesterday was a good day, today is a better day, and tomorrow will be even better.---=20 =0A --0-939785561-1299721399=:87985 Content-Type: text/html; charset=iso-8859-1 Content-Transfer-Encoding: quoted-printable

On Wed, = 3/9/11, Robert Haas <robertmhaas@gmail.com> wrote:

From: Robert H= aas <robertmhaas@gmail.com>
Subject: Re: [DOCS] Improve initdb and= pg_controldata manual pages
To: "Bruce Momjian" <bruce@momjian.us>= ;
Cc: "Tom Lane" <tgl@sss.pgh.pa.us>, "PostgreSQL-documentation" &= lt;pgsql-docs@postgresql.org>
Date: Wednesday, March 9, 2011, 12:21 P= M

On Wed, Mar 9, 2011 at 11:08 AM, Bruce Mo= mjian <bruce@momjian.us> wrote:
>> Hard to say. &= nbsp;We have the problem that our docs were made by a lot of
>> pe= ople over a long period of time, so inconsistencies are a fact of
>> life. &n= bsp;"Pro" documentation might be more consistent if it's written by a
&g= t;> smaller group of people over a shorter period of time...
>
= > We probably have higher quality but lower consistency.

Isn't co= nsistency part of quality?  I think on the whole that our docs
are = excellent in both quality and consistency.  There are things that
I= 'm not happy about, but this particular issue seems like the sort of
thi= ng that's not really worth spending effort on.  I think the
portion= s of our docs that could still use some work are the newer
portions, suc= h as the Hot Standby docs, which still feel a little
rough compared to s= ome other places - sort of a laundry list of things
that will and won't = work (UUID generators?).  I'd rather see us invest
time in general = copy editing than spend a lot of time creating an
unnecessary and possibly confusing consistency with regards to
something like this.
=
--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise Po= stgreSQL Company

--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your su= bscription:
http://www.postgresql.org/mailpref/pgsql-docs



I have to agree with Bruce M. that the docs are in need of some w= ork. I think there are two or more viewpoints.
=0A
=0AThe docs should= contain the detailed information concerning postgresql functions, with no = omissions.
=0A
=0AThe docs should be well formatted so that the PDF f= iles created are clear and understandable.
=0A
=0AThe docs need consi= stency, so that the information therein is not=0Amisconstrued by an English= speaking / reading non-American.  The=0Adocumentation has many many g= rammar mistakes, where pronouns refer back=0Ato more than one noun, or adve= rbs refer to more than one verb.  I found=0Athe authors mean very well= , but they mix usage based on programming=0Athoughts.   Fields gi= ve, instead of contains, is one example.  Here is=0Aa context to illus= trate.
=0A
=0AThe function xyz() has two variables. A list of keyword= s, and a list of=0Avalues which gives results.  Now the value variable= actually contain=0Avalues associated with keywords, and together these are= the functions=0Ainput parameters. The function does not work with keywords= alone and=0Athe result gives the values. 
=0A
=0AConsider this= example as typical of what I forwarded to Bruce M. a while back.   So= me people have ebook readers and do want to read the PDF version of the doc= s via their ebook readers.
=0A
------------------