public inbox for [email protected]  

help / color / mirror / Atom feed
From: Peter Eisentraut <[email protected]>
To: Robert Haas <[email protected]>
Cc: Andrew Dunstan <[email protected]>
Cc: [email protected] <[email protected]>
Subject: Re: documentation structure
Date: Mon, 25 Mar 2024 16:40:52 +0100
Message-ID: <[email protected]> (raw)
In-Reply-To: <CA+TgmobTb+HEx5TiTTeXF9oPxKSFftw5R0-q1UZCpETfi7wHVA@mail.gmail.com>
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>
	<[email protected]>
	<CA+TgmoYvQ=Oozena9qTpd3uGBuCWaMVSFD6xEd5qFeMJ5J4_pQ@mail.gmail.com>
	<[email protected]>
	<CA+TgmobTb+HEx5TiTTeXF9oPxKSFftw5R0-q1UZCpETfi7wHVA@mail.gmail.com>

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.







view thread (38+ messages)  latest in thread

reply
Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Reply to all the recipients using the --to and --cc options:
  reply via email

  To: [email protected]
  Cc: [email protected], [email protected], [email protected]
  Subject: Re: documentation structure
  In-Reply-To: <[email protected]>

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox