Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.92) (envelope-from ) id 1jFM4M-0004gi-74 for pgsql-hackers@arkaria.postgresql.org; Fri, 20 Mar 2020 18:08:30 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.89) (envelope-from ) id 1jFM4L-0004tv-0o for pgsql-hackers@arkaria.postgresql.org; Fri, 20 Mar 2020 18:08:29 +0000 Received: from makus.postgresql.org ([2001:4800:3e1:1::229]) by malur.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1jFM4K-0004tK-IT for pgsql-hackers@lists.postgresql.org; Fri, 20 Mar 2020 18:08:28 +0000 Received: from mail-yb1-xb42.google.com ([2607:f8b0:4864:20::b42]) by makus.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.92) (envelope-from ) id 1jFM4H-0003pE-Tb for pgsql-hackers@postgresql.org; Fri, 20 Mar 2020 18:08:27 +0000 Received: by mail-yb1-xb42.google.com with SMTP id r16so2909868ybs.13 for ; Fri, 20 Mar 2020 11:08:25 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=GQKssPaMxPNQZe9POUvdOipqRQa160Al66+arjGfwwE=; b=esxiwxAK0woAIyEJ4Wm5G10IQGLXtcqMPKkes10KBia9JgcyxHg2yJFNtmX5kgOl/T bOcgmneMuP58Kkkeg4jfP4vTBEPswoyHtKtK8hX6kU2FcFRALd1DKADzCTNcdzMiydDL HomLBrE1vPlnryqkFXZ7QFcBblFhjqq67cldYveVqdtY98UyQl/qT8yvT5q56cRk5ftB Tudw8CH5div9MxQOiUG1VA7DhHwk76jC8ItDEAxKfvMhSmd1zBBwSCH0zRToLBDGvnMN 9RrhXrDhmVUMQ3oohRYgy46p9dsvpaV0AdtMa8gTJg/2m9SrYmguW4G2VhgdId12l+/v /7pQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=GQKssPaMxPNQZe9POUvdOipqRQa160Al66+arjGfwwE=; b=TT7aBTcsFLrvUJpRnSsPDxsBZPbzEVXEXpn19oIXwb39v0+wHlBhRqoAiHxC5QGY17 5PKzUjaF60DqOC+vkg/N2g2gIZa0irh5nYzzG35RE+nLDgtlmo563EyY0Hz9OGF3eYVw bTh2K4+JQ8i6VfV4UV+DRPTswpqZKuVQ6Zf3I3sxQqmbPKIy4vBMrEYNlhAj2od4jvWY QZDtAGAAFlFnv5B1Py0g1ht7BlqYa/iLE1WmnDfXMyp6eRACE7aznrPDWvv0P9NNfA9H T+edTZDaxGOWrg76Dom4xZurGt4T+STo5abybOmws41UL61yBRjV0B9MdEBOSEYiXaIG uJLQ== X-Gm-Message-State: ANhLgQ1NhXtWBg3btQ7lnq9QSA+4kpAX3R/TUaXzxw+C9k2Mr2c59VdC lXRBZOF0Ww8n20hQOasi6oGzCqd6WezhAU3C07E= X-Google-Smtp-Source: ADFU+vtb+j6ganjej/kP2bnNMGu0csAT0rudC+DuRfIY0y0KUGfLrKJyh6LsRniVEpMQ6vvc+rxudoLnBbzA/fOWX1Q= X-Received: by 2002:a25:c68c:: with SMTP id k134mr14969425ybf.85.1584727704546; Fri, 20 Mar 2020 11:08:24 -0700 (PDT) MIME-Version: 1.0 References: <20200320175144.GA20645@alvherre.pgsql> In-Reply-To: <20200320175144.GA20645@alvherre.pgsql> From: Roger Harkavy Date: Fri, 20 Mar 2020 14:08:14 -0400 Message-ID: Subject: Re: Add A Glossary To: Alvaro Herrera Cc: Corey Huinker , =?UTF-8?Q?J=C3=BCrgen_Purtz?= , pgsql-hackers@postgresql.org, Fabien COELHO , Michael Paquier Content-Type: multipart/alternative; boundary="000000000000e531f405a14d2bd9" List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Precedence: bulk --000000000000e531f405a14d2bd9 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable Alvaro, I know that you are joking, but I want to impress on everyone: please don't feel like anyone here is breaking anything when it comes to modifying the content and structure of this glossary. I do have technical writing experience, but everyone else here is a subject matter expert when it comes to the world of databases and how this one in particular functions. On Fri, Mar 20, 2020 at 1:51 PM Alvaro Herrera wrote: > On 2020-Mar-20, Corey Huinker wrote: > > > > J=C3=BCrgen 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 m= an > > 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= =3DT > 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 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. > > -- > =C3=81lvaro Herrera https://www.2ndQuadrant.com/ > PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services > --000000000000e531f405a14d2bd9 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
Alvaro, I know that you are joking, but I want to imp= ress on everyone: please don't feel like anyone here is breaking anythi= ng when it comes to modifying the content and structure of this glossary.

I do have technical writing experience, but everyon= e else here is a subject matter expert when it comes to the world of databa= ses and how this one in particular functions.

On Fri, Mar 20, 2020= at 1:51 PM Alvaro Herrera <= alvherre@2ndquadrant.com> wrote:
On 2020-Mar-20, Corey Huinker wrote:

> > J=C3=BCrgen mentioned off-list that the man page doesn't buil= d. I was going to
> > look into that, but if anyone has more familiarity with that, I&#= 39;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 f= ailed.
I tried it here, and indeed it failed.=C2=A0 But on further investigation,<= br> after a "make maintainer-clean" it no longer failed.=C2=A0 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.=C2=A0 It's a mu= ch
slower work than I thought!=C2=A0 Attached you'll find the first few ed= its
that I propose.

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

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

I'm not sure about some terms such as "analytic" and "ba= ckend 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.=C2=A0 I'm= under the
constant impression that I'm ruining somebody's perfect end product= ,
making a fool of myself.

--
=C3=81lvaro Herrera=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 = https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
--000000000000e531f405a14d2bd9--