Re: acronym, glossary and other related matters in the docs

On Fri, Mar 21, 2025 at 1:55 PM Andres Freund <andres(at)anarazel(dot)de> wrote:

> Hi,
>
> I was trying to write some docs for an AIO related view. As part of that I
> noticed that we referenced I/O a lot, but never defined it as an acronym or
> had it in the glossary. While adding those I got somewhat confused by
> things
> that have confused me in the past:
>
> 1) When are we supposed to use <acronym>IDK</acronym> and when not? We
> seem to
> be extremely inconsistent. E.g.
> git grep -P 'WAL(?=\</acronym)' doc/|wc -l
> 42
> git grep -P 'WAL(?!\</acronym)' doc/|wc -l
> 904
>
> Given that, at least for html, <acronym> doesn't change the display,
> that's
> perhaps not too surprising. But if we don't do it consistently, perhaps
> we
> should just stop doing it at all?
>

See recent discussion regarding TOAST.

https://www.postgresql.org/message-id/CAKFQuwaOXpOuYwN%3D8s3%2Bm-nRv5-Dgr_borfcRFmmjBxtg7kwXA%40mail.gmail.com

The vast majority of our uses of WAL can easily be considered using it as
part of a noun and not as an acronym.

I haven't pondered I/O.

> 2) We have glossary entries explaining acronyms, but we rarely reference
> them. Is there a reason for that? It'd probably be silly to link
> glossary
> entries every time an acronym is used, often there are many uses
> close-by,
> but that doesn't mean we shouldn't ever do it?
>
> ISTM we should have a guideline for this.
>

I'm leaning toward not linking glossary entries in general. Most concepts
that you'd want to link there have actually sections in the documentation
that would be better linked to instead. And linking from those sections to
the glossary seems redundant.

The glossary is basically a description-augmented index. You go there if
you see a term in the wild you are unfamiliar with to see its description
and get links into the main documentation for further discussion. Or to
the index to see more completely all the places where it is mentioned.
Like the index it is an interface to the outside world.

> 4) We don't put the glossary entries in the index, despite that sometimes
> being the only place something is documented.
>
>
Extending from my observation above, the glossary and index should probably
cross-reference each other.

David J.