Horton

Re: documentation structure

Robert Haas <robertmhaas@gmail.com>

View thread
From: Robert Haas <robertmhaas@gmail.com>
To: "David G. Johnston" <david.g.johnston@gmail.com>
Cc: Andrew Dunstan <andrew@dunslane.net>, "pgsql-hackers@postgresql.org" <pgsql-hackers@postgresql.org>
Date: 2024-03-22T12:32:14Z
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 Thu, Mar 21, 2024 at 6:32 PM David G. Johnston
<david.g.johnston@gmail.com> wrote:
> Just going to note that the section on the cumulative statistics views being a single page is still a strongly bothersome issue here.  Though the quick fix actually requires upgrading the section to chapter status...

Yeah, I've been bothered by this in the past, too. I'm not very keen
to start promoting things to the top-level, though. I think we need a
more thoughtful fix than that.

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
title that gives no hint that it will document any views.

> Maybe "pl/pgsql and Other Procedural Languages" as the title?

I guess I have a hard time seeing this as an improvement. It would
help someone who knows that plpgsql exists but doesn't know that it
falls into the general category called procedural languages, but I
suspect that's not a very common confusion. I think it's better to
keep the chapter titles short and to the point.

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