Re: TOC: List of Figures

From: Jürgen Purtz <juergen(at)purtz(dot)de>
To: pgsql-docs(at)lists(dot)postgresql(dot)org
Subject: Re: TOC: List of Figures
Date: 2019-07-08 05:20:51
Message-ID: 9c19b21a-cc58-9aed-7be5-f3311b98466f@purtz.de
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-docs

> Peter Eisentraut <peter(dot)eisentraut(at)2ndquadrant(dot)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

In response to

Responses

Browse pgsql-docs by date

  From Date Subject
Next Message PG Doc comments form 2019-07-08 10:07:59 Ambiguous language in Table 8.13. Special Date/Time Inputs
Previous Message Tom Lane 2019-07-07 18:37:58 Re: TOC: List of Figures