Horton

Re: documentation structure

Robert Haas <robertmhaas@gmail.com>

View thread
From: Robert Haas <robertmhaas@gmail.com>
To: Bruce Momjian <bruce@momjian.us>
Cc: "David G. Johnston" <david.g.johnston@gmail.com>, Andrew Dunstan <andrew@dunslane.net>, "pgsql-hackers@postgresql.org" <pgsql-hackers@postgresql.org>
Date: 2024-03-22T18:19:29Z
Lists: pgsql-hackers

Commits

Same data as JSON: GET /api/v1/messages/:b64id/commits the thread's linked commits as JSON, with link sources. API reference →

  1. docs: Consistently use <optional> to indicate optional parameters

  2. docs: Consolidate into new "WAL for Extensions" chapter.

  3. freespace: Don't return blocks past the end of the main fork.

  4. docs: Merge separate chapters on built-in index AMs into one.

  5. docs: Demote "Monitoring Disk Usage" from chapter to section.

  6. doc: move system views section to its own chapter

On Fri, Mar 22, 2024 at 1:35 PM Bruce Momjian <bruce@momjian.us> wrote:
> > One question I have is why all of these views are documented here
> > rather than in chapter 53, "System Views," because surely they are
> > system views. I feel like if our documentation index weren't a mile
> > long and if you could easily find the entry for "System Views," that's
> > where you would naturally look for these details. I don't think it's
> > natural for a user to expect that most of the system views are going
> > to be documented in section VII, chapter 53 but one particular kind is
> > going to be documented in section III, chapter 27, under a chapter
>
> Well, until this commit in 2022, the system views were _under_ the
> system catalogs chapter:

Even before that commit, the statistics collector views were
documented in a completely separate part of the documentation from all
of the other system views.

I think that commit was a good idea, even though it made the top-level
documentation index bigger, because in v14, the "System Catalogs"
chapter looks like this:

...
52.61. pg_ts_template
52.62. pg_type
52.63. pg_user_mapping
52.64. System Views
52.65. pg_available_extensions
52.66. pg_available_extension_versions
52.67. pg_backend_memory_contexts
...

If you were actually looking for the section called "System Views",
you weren't likely to see it here unless you already knew it was
there, because it was 64 items into a 97-item list. Having one of
these two sections inside the other just doesn't work at all. We could
have alternatively chosen to have one chapter with two <sect1> tags
inside of it, but I think what you actually did was perfectly fine.
IMHO, "System Views" is important enough (and big enough) that giving
it its own chapter is perfectly reasonable.

But that all seems like a separate question from why we have the
statistic collector views in a completely different part of the
documentation from the rest of the system views. My guess is that it's
just kind of a historical accident, but maybe there was some other
logic to it.

-- 
Robert Haas
EDB: http://www.enterprisedb.com