Subject: Re: Some doc suggestions
To: Justin Dearing <zippy1981@gmail.com>, pgsql-docs@postgresql.org
References: 
 <CABsCM1OLA=Z1C4y5_qzBdYPs-_XJh2S3Q=NMH=SZvi4c+ioy3g@mail.gmail.com>
From: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
Organization: 2ndQuadrant
Message-ID: <04973fe6-b622-962b-e7cf-0a89a2547500@2ndquadrant.com>
Date: Sat, 9 Jul 2016 09:55:09 -0400
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.11; rv:45.0)
 Gecko/20100101 Thunderbird/45.1.1
MIME-Version: 1.0
In-Reply-To: 
 <CABsCM1OLA=Z1C4y5_qzBdYPs-_XJh2S3Q=NMH=SZvi4c+ioy3g@mail.gmail.com>
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Transfer-Encoding: 7bit
Precedence: bulk
Sender: pgsql-docs-owner@postgresql.org

On 6/23/16 10:37 PM, Justin Dearing wrote:
> Switched jobs recently and returning to postgres after a long hiatus.
> The docs are great, but I noticed a few things  that could be improved
> in the area of catalot documentations.
>
>  1. The CREATE/ALTER/DROP doc pages should have a link to the
>     corresponding pg_catalog and INFORMATION_schema tables and views for
>     that object type.

The correspondence between these three is not exactly as cleanly 
one-to-one as one might think.  I think this would be very confusing and 
not really helpful in practice.

>  2. pg_catalog docs should have a link to their corresponding
>     information_schema table or view and visa versa.

same here

>  3. Perhaps this page (and its
>     analogs) https://www.postgresql.org/docs/9.1/static/catalogs.html should
>     have a 1-3 word description of each catalog. Some are unintuitive.
>     For example it took awhile to figure out pg_attribute was the list
>     of columns.

That is an automatically generated table of contents.

>  4. OID columns should have a note saying something to the effect of "to
>     get the text name of this simply use atttypid::REGTYPE"

We link the OID columns to their corresponding primary key table.  We 
don't have reg* types for everything anyway.

>  5. I discovered that pg_catalog.name <http://pg_catalog.name> is a
>     built in type today, but its not listed as a built in type. I've yet
>     to find it in the docs. It should either be listed in the built in
>     types, or the list of built in types should link to the list of
>     "other built in types" whereever they are.

You're right.

> If any of those suggestions are ameanable where are the docs for
> contributing to the docs?

You can send a patch to this list.  It's not very different from 
contributing code.

-- 
Peter Eisentraut              http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services


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