Content-Type: text/plain; charset=UTF-8
Cc: PostgreSQL-documentation <pgsql-docs@postgresql.org>
Subject: Re: Improve initdb and pg_controldata manual pages
From: Alvaro Herrera <alvherre@commandprompt.com>
To: Leslie S Satenstein <lsatenstein@yahoo.com>
In-reply-to: <59974.87985.qm@web110707.mail.gq1.yahoo.com>
References: <59974.87985.qm@web110707.mail.gq1.yahoo.com>
Date: Thu, 10 Mar 2011 11:43:31 -0300
Message-Id: <1299767607-sup-5201@alvh.no-ip.org>
User-Agent: Sup/git
Content-Transfer-Encoding: 8bit

Excerpts from Leslie S Satenstein's message of mié mar 09 22:43:19 -0300 2011:

> I have to agree with Bruce M. that the docs are in need of some work.
> I think there are two or more viewpoints.

I don't think you're going to find anyone to state that the docs are
perfect.  Most people will say that they're “pretty good”, but agree
that improvements are still possible.

> The docs should contain the detailed information concerning postgresql
> functions, with no omissions.

No disagreement on this, but maybe there are corner cases.

> The docs should be well formatted so that the PDF files created are
> clear and understandable.

No disagreement on this either.  I was even thinking a couple of days
ago that it might be good to have PDFs in other page sizes, smaller than
A4; say a typical book size.  That would perhaps display better on a
ebook reader.  (On the readers I've seen, full-page PDFs are annoying to
browse: fonts are too small, or you have to scroll).

Also, we still have program output, tables or code samples that are too
wide to fit a page.  Those need to be fixed too.

Another thing I've considered is to format Postgres table output as
Docbook tables instead of ASCII art.  Perhaps that would render better.
But that needs to be explored.  (And of course psql would need a docbook
output mode to facilitate doc writing).

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

Not being a native english speaker, I can't help you here.

-- 
Álvaro Herrera <alvherre@commandprompt.com>
The PostgreSQL Company - Command Prompt, Inc.
PostgreSQL Replication, Consulting, Custom Development, 24x7 support