Re: documentation structure

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.