From: Jürgen Purtz <juergen@purtz.de>
To: pgsql-docs@lists.postgresql.org
Subject: Re: TOC: List of Figures
Date: Mon, 8 Jul 2019 07:20:51 +0200
Message-ID: <9c19b21a-cc58-9aed-7be5-f3311b98466f@purtz.de> (raw)
In-Reply-To: <30333.1562524678@sss.pgh.pa.us>
References: <e9e5faa4-e920-3253-f6bb-794109e228a1@purtz.de>
<304820c6-2ef5-0fdd-4610-1a09b970d9ef@2ndquadrant.com>
<30333.1562524678@sss.pgh.pa.us>
> Peter Eisentraut <peter.eisentraut@2ndquadrant.com> writes:
>> On 2019-07-02 10:13, Jürgen Purtz wrote:
>>> After the integration of figures into the documentation it may be
>>> helpful to extent the TOC with a 'List of Figures'. Any opinion?
>>>
>>> If yes: The same for 'List of Tables' and 'List of Examples'?
>> I have never found these useful. What would you use them for? Who goes
>> to the documentation (or any other book-like material) thinking, I'm in
>> the mood to look at some tables today, let's see what's in them.
> +1. I have a vague recollection that we once had such lists in the
> TOC (because that was the default behavior for whatever toolchain we
> were then using) and later took them out precisely because they were
> useless. Not sure how a list of figures would be any more useful.
>
> regards, tom lane
>
The two main reasons for using the documentation are 'reference for
concepts and syntax' and 'learning'. For the first issue figures are
less important - at least as BNF is not presented graphically. The
second issue is important for all persons which are not very familiar
with PG. Pedagogues tell us, that learning is done best with different
media types, where typical methods are direct speech, videos (see the
huge number of learning videos at YouTube), graphics, exercises, reading
manuals. In essence, they recommend some kind of 'media changes' within
each lesson. Currently our documentation is not much more than a manual,
the rising element 'graphics' is and will be tiny small (unless we
integrate BNF). To support the didactic method of media changes we
should promote graphics with a summarizing list at a prominent place in
front of the manual.
Kind regards, Jürgen Purtz
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: pgsql-docs@postgresql.org
Cc: juergen@purtz.de, pgsql-docs@lists.postgresql.org
Subject: Re: TOC: List of Figures
In-Reply-To: <9c19b21a-cc58-9aed-7be5-f3311b98466f@purtz.de>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox