Re: Add A Glossary

From: Alvaro Herrera <alvherre(at)2ndquadrant(dot)com>
To: Corey Huinker <corey(dot)huinker(at)gmail(dot)com>
Cc: Jürgen Purtz <juergen(at)purtz(dot)de>, Roger Harkavy <rogerharkavy(at)gmail(dot)com>, pgsql-hackers(at)postgresql(dot)org, Fabien COELHO <coelho(at)cri(dot)ensmp(dot)fr>, Michael Paquier <michael(at)paquier(dot)xyz>
Subject: Re: Add A Glossary
Date: 2020-03-20 17:51:44
Message-ID: 20200320175144.GA20645@alvherre.pgsql
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-docs pgsql-hackers

On 2020-Mar-20, Corey Huinker wrote:

> > Jürgen mentioned off-list that the man page doesn't build. I was going to
> > look into that, but if anyone has more familiarity with that, I'm listening.

> Looking at this some more, I'm not sure anything needs to be done for man
> pages.

Yeah, I don't think he was saying that we needed to do anything to
produce a glossary man page; rather that the "make man" command failed.
I tried it here, and indeed it failed. But on further investigation,
after a "make maintainer-clean" it no longer failed. I'm not sure what
to make of it, but it seems that this patch needn't concern itself with
that.

I gave a read through the first few actual definitions. It's a much
slower work than I thought! Attached you'll find the first few edits
that I propose.

Looking at the definition of "Aggregate" it seemed weird to have it
stand as a verb infinitive. I looked up other glossaries, found this
one
https://www.gartner.com/en/information-technology/glossary?glossaryletter=T
and realized that when they do verbs, they put the present participle
(-ing) form. So I changed it to "Aggregating", and split out the
"Aggregate function" into its own term.

In Atomic, there seemed to be excessive use of <glossterm> in the
definitions. Style guides seem to suggest to do that only the first
time you use a term in a definition. I removed some markup.

I'm not sure about some terms such as "analytic" and "backend server".
I put them in XML comments for now.

The other changes should be self-explanatory.

It's hard to review work from a professional tech writer. I'm under the
constant impression that I'm ruining somebody's perfect end product,
making a fool of myself.

--
Álvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

Attachment Content-Type Size
glossary-3.patch text/x-diff 7.7 KB

In response to

Responses

Browse pgsql-docs by date

  From Date Subject
Next Message Roger Harkavy 2020-03-20 18:08:14 Re: Add A Glossary
Previous Message Corey Huinker 2020-03-20 15:48:24 Re: Add A Glossary

Browse pgsql-hackers by date

  From Date Subject
Next Message Roger Harkavy 2020-03-20 18:08:14 Re: Add A Glossary
Previous Message Tom Lane 2020-03-20 16:42:42 Re: Correlated IN/Any Subquery Transformation