Re: Add A Glossary - Mailing list pgsql-hackers

Hello Corey,

My 0.02€:

On principle, I'm fine with having a glossary, i.e. word definitions, 
which are expected to be rather stable in the long run.

I'm wondering whether the effort would not be made redundant by other 
on-line effort such as wikipedia, wiktionary, stackoverflow, standards, 
whatever.

When explaining something, the teacher I am usually provides some level of 
example. This may or may not be appropriate there.

ISTM that there should be pointers to relevant sections in the 
documentation, for instance "Analytics" provided definition suggests
pointing to windowing functions.

There is significant redundancy involved, because a lot of term would be 
defined in other sections anyway.

There should be cross references, eg "Column" definition talks about 
Attribute, Table & View, which should be linked to.

I'd consider making SQL keywords uppercase.

Developing that is a significant undertaking. Do we have the available 
energy?

Patch generates a warning on "git apply".

  sh> git apply ...
  ... terms-and-definitions.patch:159: tab in indent. [...]
  warning: 1 line adds whitespace errors.

"Record" def as nested <para> for some unclear reason.

Basically the redacted definitions look pretty clear and well written to 
the non-native English speaker I am.

On Sun, 13 Oct 2019, Corey Huinker wrote:

> Date: Sun, 13 Oct 2019 16:52:05 -0400
> From: Corey Huinker <corey.huinker@gmail.com>
> To: pgsql-hackers@postgresql.org
> Subject: Add A Glossary
> 
> Attached is a v1 patch to add a Glossary to the appendix of our current
> documentation.
>
> I believe that our documentation needs a glossary for a few reasons:
>
> 1. It's hard to ask for help if you don't know the proper terminology of
> the problem you're having.
>
> 2. Readers who are new to databases may not understand a few of the terms
> that are used casually both in the documentation and in forums. This helps
> to make our documentation a bit more useful as a teaching tool.
>
> 3. Readers whose primary language is not English may struggle to find the
> correct search terms, and this glossary may help them grasp that a given
> term has a usage in databases that is different from common English usage.
>
> 3b. If we are not able to find the resources to translate all of the
> documentation into a given language, translating the glossary page would be
> a good first step.
>
> 4. The glossary would be web-searchable, and draw viewers to the official
> documentation.
>
> 5. adding link anchors to each term would make them cite-able, useful in
> forum conversations.
>
>
> A few notes about this patch:
>
> 1. It's obviously incomplete. There are more terms, a lot more, to add.
>
> 2. The individual definitions supplied are off-the-cuff, and should be
> thoroughly reviewed.
>
> 3. The definitions as a whole should be reviewed by an actual tech writer
> (one was initially involved but had to step back due to prior commitments),
> and the definitions should be normalized in terms of voice, tone, audience,
> etc.
>
> 4. My understanding of DocBook is not strong. The glossary vs glosslist tag
> issue is a bit confusing to me, and I'm not sure if the glossary tag is
> even appropriate for our needs.
>
> 5. I've made no effort at making each term an anchor, nor have I done any
> CSS styling at all.
>
> 6. I'm not quite sure how to handle terms that have different definitions
> in different contexts. Should that be two glossdefs following one
> glossterm, or two separate def/term pairs?
>
> Please review and share your thoughts.
>

-- 
Fabien Coelho - CRI, MINES ParisTech