public inbox for [email protected]
help / color / mirror / Atom feedFrom: Roger Harkavy <[email protected]>
To: Alvaro Herrera <[email protected]>
Cc: Corey Huinker <[email protected]>
Cc: Jürgen Purtz <[email protected]>
Cc: [email protected]
Cc: Fabien COELHO <[email protected]>
Cc: Michael Paquier <[email protected]>
Subject: Re: Add A Glossary
Date: Fri, 20 Mar 2020 14:08:14 -0400
Message-ID: <CAM-7Z-rdStk06fd0yk9ZiQ2_8noxnCdcf4Mu-z8-hABdJpb2iA@mail.gmail.com> (raw)
In-Reply-To: <[email protected]>
References: <CADkLM=dTFNCnx+bdoVCVbAn3v8ihvgUh-dQpin4ngrx=RMykFA@mail.gmail.com>
<[email protected]>
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 <[email protected]>
wrote:
> 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
>
view thread (97+ messages) latest in thread
reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: [email protected]
Cc: [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected]
Subject: Re: Add A Glossary
In-Reply-To: <CAM-7Z-rdStk06fd0yk9ZiQ2_8noxnCdcf4Mu-z8-hABdJpb2iA@mail.gmail.com>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox