MIME-Version: 1.0
From: Justin Dearing <zippy1981@gmail.com>
Date: Fri, 24 Jun 2016 02:37:29 +0000
Message-ID: 
 <CABsCM1OLA=Z1C4y5_qzBdYPs-_XJh2S3Q=NMH=SZvi4c+ioy3g@mail.gmail.com>
Subject: Some doc suggestions
To: pgsql-docs@postgresql.org
Content-Type: multipart/alternative; boundary=001a114e572ad4fbe30535fd0d87
Precedence: bulk
Sender: pgsql-docs-owner@postgresql.org

--001a114e572ad4fbe30535fd0d87
Content-Type: text/plain; charset=UTF-8

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
   2. pg_catalog docs should have a link to their corresponding
   information_schema table or view and visa versa.
   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.
   4. OID columns should have a note saying something to the effect of "to
   get the text name of this simply use atttypid::REGTYPE"
   5. I discovered that 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.

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

Regards,

Justin Dearing

--001a114e572ad4fbe30535fd0d87
Content-Type: text/html; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

<div dir=3D"ltr">Switched jobs recently and returning to postgres after a l=
ong hiatus. The docs are great, but I noticed a few things =C2=A0that could=
 be improved in the area of catalot documentations.<div><br></div><div><ol>=
<li><span style=3D"line-height:1.5">The CREATE/ALTER/DROP doc pages should =
have a link to the corresponding pg_catalog and INFORMATION_schema tables a=
nd views for that object type. The=C2=A0</span><br></li><li>pg_catalog docs=
 should have a link to their corresponding information_schema table or view=
 and visa versa.</li><li>Perhaps this page (and its analogs)=C2=A0<a href=
=3D"https://www.postgresql.org/docs/9.1/static/catalogs.html">https://www.p=
ostgresql.org/docs/9.1/static/catalogs.html</a>=C2=A0should have a 1-3 word=
 description of each catalog. Some are unintuitive. For example it took awh=
ile to figure out pg_attribute was the list of columns.</li><li>OID columns=
 should have a note saying something to the effect of &quot;to get the text=
 name of this simply use=C2=A0atttypid::REGTYPE&quot;</li><li>I discovered =
that <a href=3D"http://pg_catalog.name">pg_catalog.name</a> is a built in t=
ype today, but its not listed as a built in type. I&#39;ve yet to find it i=
n the docs. It should either be listed in the built in types, or the list o=
f built in types should link to the list of &quot;other built in types&quot=
; whereever they are.</li></ol><div>If any of those suggestions are ameanab=
le where are the docs for contributing to the docs?</div></div><div><br></d=
iv><div>Regards,</div><div><br></div><div>Justin Dearing</div></div>

--001a114e572ad4fbe30535fd0d87--