Subject: Re: TOC: List of Figures
To: pgsql-docs@lists.postgresql.org
References: <e9e5faa4-e920-3253-f6bb-794109e228a1@purtz.de>
 <304820c6-2ef5-0fdd-4610-1a09b970d9ef@2ndquadrant.com>
 <30333.1562524678@sss.pgh.pa.us>
From: =?UTF-8?Q?J=c3=bcrgen_Purtz?= <juergen@purtz.de>
Message-ID: <9c19b21a-cc58-9aed-7be5-f3311b98466f@purtz.de>
Date: Mon, 8 Jul 2019 07:20:51 +0200
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101
 Thunderbird/60.7.2
MIME-Version: 1.0
In-Reply-To: <30333.1562524678@sss.pgh.pa.us>
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Transfer-Encoding: 8bit
Content-Language: en-US
Precedence: bulk

> 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