public inbox for [email protected]
help / color / mirror / Atom feedFrom: Peter Eisentraut <[email protected]>
To: Justin Dearing <[email protected]>
To: [email protected]
Subject: Re: Some doc suggestions
Date: Sat, 9 Jul 2016 09:55:09 -0400
Message-ID: <[email protected]> (raw)
In-Reply-To: <CABsCM1OLA=Z1C4y5_qzBdYPs-_XJh2S3Q=NMH=SZvi4c+ioy3g@mail.gmail.com>
References: <CABsCM1OLA=Z1C4y5_qzBdYPs-_XJh2S3Q=NMH=SZvi4c+ioy3g@mail.gmail.com>
List-Unsubscribe: <mailto:[email protected]?body=unsub%20pgsql-docs>
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 ([email protected])
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
view thread (3+ messages)
reply
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: [email protected]
Cc: [email protected], [email protected]
Subject: Re: Some doc suggestions
In-Reply-To: <[email protected]>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox