Feedback-ID: ia2694551:Fastmail
Date: Mon, 13 Nov 2023 12:20:15 +0100
From: Alvaro Herrera <alvherre@alvh.no-ip.org>
To: Daniel Gustafsson <daniel@yesql.se>
Cc: alaa.attya91@gmail.com, pgsql-docs@lists.postgresql.org
Subject: Re: add new acronym "AM"
Message-ID: <202311131120.pavqs3etyreu@alvherre.pgsql>
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: <6C63CE33-0F77-4E12-AC8D-3CB6E5C4FD40@yesql.se>
Archived-At: 
 <https://www.postgresql.org/message-id/202311131120.pavqs3etyreu%40alvherre.pgsql>
Precedence: bulk

On 2023-Nov-13, Daniel Gustafsson wrote:

> That's a fair point.  It's sort of hard to refer back from the acronym list
> though since we don't have a single Access Method section but instead one for
> Indexes and one for Relations.  In the attached diff I propose that we add a
> glossary entry for Access Method (suggested better wording much appreciated)
> which the acronym can refer to.  Being such a core concept it doesn't seem like
> a bad idea to explain it.

+1 for a glossary entry.

+     Access methods are the interfaces which
+     <productname>PostgreSQL</productname> use in order to access relations
+     and indexes. This abstraction allows for adding support for new
+     types of tuple storage. For more information, see <xref linkend="indexam" />
+     and <xref linkend="tableam" />.

We don't start the glossary definition with the term we're defining.
For example, we say
  Atomicity
  The property of a transaction that ...
we don't say
  Atomicity
  Atomicity is the property of ...

So you would want your definition to be something like
"Interfaces which PostgreSQL use to ..."

I'd say "data in tables and indexes" rather than "relations and
indexes", and "data storage" instead of "tuple storage".

"For more information" should be its own <para>.

-- 
Álvaro Herrera         PostgreSQL Developer  —  https://www.EnterpriseDB.com/
Si no sabes adonde vas, es muy probable que acabes en otra parte.