[DOCS] Some doc suggestions

[Justin Dearing]

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

[Justin Dearing]

Ok addendu, it seems like the overview page for catalogs has exactly what I
asked for in the contents page. Any reason they can't be merged? Is it just
the nature of the doc system? As a postgres outsider, it seemed kinda
obtuse.

Post by Justin Dearing
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

[Peter Eisentraut]

Post by Justin Dearing
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.

Post by Justin Dearing
2. pg_catalog docs should have a link to their corresponding
information_schema table or view and visa versa.

same here

Post by Justin Dearing
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.

Post by Justin Dearing
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.

Post by Justin Dearing
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.

Post by Justin Dearing
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.