From: Leslie S Satenstein <lsatenstein@yahoo.com>
To: PostgreSQL-documentation <pgsql-docs@postgresql.org>
Subject: Improve initdb and pg_controldata manual pages
Date: Wed, 9 Mar 2011 17:43:19 -0800 (PST)
Message-ID: <59974.87985.qm@web110707.mail.gq1.yahoo.com> (raw)
In-Reply-To: <AANLkTinSpRATNbdLnZxHX+wVniuXU-PUvyMLxr+7_ab2@mail.gmail.com>
On Wed, 3/9/11, Robert Haas <robertmhaas@gmail.com> wrote:
From: Robert Haas <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" <pgsql-docs@postgresql.org>
Date: Wednesday, March 9, 2011, 12:21 PM
On Wed, Mar 9, 2011 at 11:08 AM, Bruce Momjian <bruce@momjian.us> wrote:
>> Hard to say. We 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. "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? 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
thing that's not really worth spending effort on. 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?). 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 PostgreSQL Company
--
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 think there are two or more viewpoints.
The docs should contain the detailed information concerning postgresql functions, with no omissions.
The docs should be well formatted so that the PDF files created are clear and understandable.
The docs need consistency, so that the information therein is not
misconstrued by an English speaking / reading non-American. The
documentation has many many grammar mistakes, where pronouns refer back
to more than one noun, or adverbs refer to more than one verb. I found
the authors mean very well, but they mix usage based on programming
thoughts. Fields give, instead of contains, is one example. Here is
a context to illustrate.
The function xyz() has two variables. A list of keywords, and a list of
values which gives results. Now the value variable actually contain
values associated with keywords, and together these are the functions
input parameters. The function does not work with keywords alone and
the result gives the values.
Consider this example as typical of what I forwarded to Bruce M. a while back. Some people have ebook readers and do want to read the PDF version of the docs via their ebook readers.
------------------
p.MsoNormal, li.MsoNormal, div.MsoNormal { margin: 0in 0in 0.0001pt; font-size: 12pt; font-family: "Times New Roman"; }filtered { margin: 1in 1.25in; }div.Section1 { }Regards
Leslie
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.---
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: lsatenstein@yahoo.com
Subject: Re: Improve initdb and pg_controldata manual pages
In-Reply-To: <59974.87985.qm@web110707.mail.gq1.yahoo.com>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox