Feedback-ID: ie0a040ee:Fastmail
Message-ID: <682e11bd-07b9-4d8b-8bef-4990a13e0d22@eisentraut.org>
Date: Mon, 25 Mar 2024 16:40:52 +0100
MIME-Version: 1.0
User-Agent: Mozilla Thunderbird
Subject: Re: documentation structure
To: Robert Haas <robertmhaas@gmail.com>
Cc: Andrew Dunstan <andrew@dunslane.net>,
 "pgsql-hackers@postgresql.org" <pgsql-hackers@postgresql.org>
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>
Content-Language: en-US
From: Peter Eisentraut <peter@eisentraut.org>
In-Reply-To: <CA+TgmobTb+HEx5TiTTeXF9oPxKSFftw5R0-q1UZCpETfi7wHVA@mail.gmail.com>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 7bit
Archived-At: <https://www.postgresql.org/message-id/682e11bd-07b9-4d8b-8bef-4990a13e0d22%40eisentraut.org>
Precedence: bulk

On 22.03.24 15:10, Robert Haas wrote:
> Sorry. I didn't mean to dispute the point that the section was added a
> few years ago, nor the point that most people just want to read about
> the binaries. I am confident that both of those things are true. What
> I do want to dispute is that having a four-sentence chapter in the
> documentation index that tells people something they can find much
> more easily without using the documentation at all is a good plan.

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

<chapter> Installation
  <sect1>   Installation from Binaries
  <sect1>   Installation from Source
   <sect2>   Requirements
   <sect2>   Getting the Source
   <sect2>   Building and Installation with Autoconf and Make
   <sect2>   Building and Installation with Meson
etc.

This would mean that the entire "Installation from Source" part would be 
rendered on a single HTML page.

The rendering can be adjusted to some degree, but then we also need to 
make sure any new chunking makes sense in other chapters.  (And it might 
also change a bunch of externally known HTML links.)

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.