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.comThe 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-docsI 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.---