public inbox for [email protected]help / color / mirror / Atom feed
Some doc suggestions 3+ messages / 2 participants [nested] [flat]
* Some doc suggestions @ 2016-06-24 02:37 Justin Dearing <[email protected]> 0 siblings, 2 replies; 3+ messages in thread From: Justin Dearing @ 2016-06-24 02:37 UTC (permalink / raw) To: pgsql-docs 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 ^ permalink raw reply [nested|flat] 3+ messages in thread
* Re: Some doc suggestions @ 2016-06-24 02:42 Justin Dearing <[email protected]> parent: Justin Dearing <[email protected]> 1 sibling, 0 replies; 3+ messages in thread From: Justin Dearing @ 2016-06-24 02:42 UTC (permalink / raw) To: pgsql-docs 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. On Thu, Jun 23, 2016 at 10:37 PM Justin Dearing <[email protected]> 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 > 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 > ^ permalink raw reply [nested|flat] 3+ messages in thread
* Re: Some doc suggestions @ 2016-07-09 13:55 Peter Eisentraut <[email protected]> parent: Justin Dearing <[email protected]> 1 sibling, 0 replies; 3+ messages in thread From: Peter Eisentraut @ 2016-07-09 13:55 UTC (permalink / raw) To: Justin Dearing <[email protected]>; pgsql-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 ^ permalink raw reply [nested|flat] 3+ messages in thread
end of thread, other threads:[~2016-07-09 13:55 UTC | newest] Thread overview: 3+ messages (download: mbox mbox.gz follow: Atom feed) -- links below jump to the message on this page -- 2016-06-24 02:37 Some doc suggestions Justin Dearing <[email protected]> 2016-06-24 02:42 ` Justin Dearing <[email protected]> 2016-07-09 13:55 ` Peter Eisentraut <[email protected]>
This inbox is served by agora; see mirroring instructions for how to clone and mirror all data and code used for this inbox