MIME-Version: 1.0
References: <CA+TgmoZ2F+K0j=6BOJLD=YfpJMdJRXC7sWmtXGRjx1Rq0x8PUA@mail.gmail.com>
 <CAD5tBcJUVQu=9zpr9C+Z=3SjxrECURtr_i1oipMqke4dpZXtyQ@mail.gmail.com>
 <CA+TgmobvXwu+iJmBg3hncdjY0-agg3giP-aLi_KhDyrL9+OLew@mail.gmail.com>
 <e2b6a52e-39bf-4627-adec-8a7366dd4d32@eisentraut.org> <CA+TgmoYvQ=Oozena9qTpd3uGBuCWaMVSFD6xEd5qFeMJ5J4_pQ@mail.gmail.com>
 <33e82e2a-3954-4c1e-8114-ffbd8dfb5293@eisentraut.org> <CA+TgmobTb+HEx5TiTTeXF9oPxKSFftw5R0-q1UZCpETfi7wHVA@mail.gmail.com>
 <682e11bd-07b9-4d8b-8bef-4990a13e0d22@eisentraut.org>
In-Reply-To: <682e11bd-07b9-4d8b-8bef-4990a13e0d22@eisentraut.org>
From: Robert Haas <robertmhaas@gmail.com>
Date: Mon, 25 Mar 2024 12:01:28 -0400
Message-ID: <CA+TgmoYaTBdGf_YLe5PtW51wxF3ZSYHLfXzNFGzNCV0ffNkpgw@mail.gmail.com>
Subject: Re: documentation structure
To: Peter Eisentraut <peter@eisentraut.org>
Cc: Andrew Dunstan <andrew@dunslane.net>, 
	"pgsql-hackers@postgresql.org" <pgsql-hackers@postgresql.org>
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
Archived-At: <https://www.postgresql.org/message-id/CA%2BTgmoYaTBdGf_YLe5PtW51wxF3ZSYHLfXzNFGzNCV0ffNkpgw%40mail.gmail.com>
Precedence: bulk

On Mon, Mar 25, 2024 at 11:40=E2=80=AFAM Peter Eisentraut <peter@eisentraut=
.org> wrote:
> I think a possible problem we need to consider with these proposals to
> combine chapters is that they could make the chapters themselves too
> deep and harder to navigate.  For example, if we combined the
> installation from source and binaries chapters, the structure of the new
> chapter would presumably be

I agree with this in theory, but in practice I think the patches that
I posted don't have this issue to a degree that is problematic, and I
posted some specific proposals on adjustments that we could make to
ameliorate the problem if other people feel differently.

> I think maybe more could also be done at the top-level structure, too.
> Right now, we have <book> -> <part> -> <chapter>.  We could add <set> on
> top of that.
>
> We could also play with CSS or JavaScript to make the top-level table of
> contents more navigable, with collapsing subsections or whatever.
>
> We could also render additional tables of contents or indexes, so there
> is more than one way to navigate into the content from the top.
>
> We could also build better search.

These are all reasonable ideas. I think some better CSS and JavaScript
could definitely help, and I also wondered whether the entrypoint to
the documentation has to be the index page, or whether it could maybe
be a page we've crafted specifically for that purpose, that might
include some text as well as a bunch of links.

But that having been said, I don't believe that any of those ideas (or
anything else we do) will obviate the need for some curation of the
toplevel index. If you're going to add another level, as you propose
in the first point, you still need to make decisions about which
things properly go at which levels. If you're going to allow for
collapsing subsections, you still want the overall tree in which
subsections are be expanded and collapsed to make logical sense. If
you have multiple ways to navigate to the content, one of them will
probably be still the index, and it should be good. And good search is
good, but it shouldn't be the only convenient way to find the content.

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