Thread: [Doc] Glossary Term Definitions Edits

[Doc] Glossary Term Definitions Edits

From
Andrew Atkinson
Date:
Hello. I started reading through the Glossary[^1] terms to learn from the definitions, and to double check them against what I'd written elsewhere. I found myself making edits. :)

I've put the edits together into a patch. My goal was to focus on wording simplifications that are smoother to read, without big changes.

I realized I should check with others though, so this is a mid-point check-in. For now I went through terms from "A" through "I".


Here's a recap of the changes:


  • Changed places like “to make” to use the verb directly, i.e. “make”
  • When describing options for a command, changed to “option of” instead of “option to”
  • “system- or user-supplied”, removed the dash after system. Or I’d suggest system-supplied or user-supplied, to hyphenate both.
  • Changed “will access”  to “access”
  • Changed “helps to prevent” to “helps prevent”
  • Changed “volume of records has been written” to “volume of records were written”
  • “It is required that this user exist” changed to “This user is required to exist...” (I’d also suggest “This user must exist before”) as a simplification, but that’s a bigger difference from what’s there now.
  • Changed “operating-system” to remove the hyphen, which is how it’s written elsewhere in the Glossary.
  • Many examples of “an SQL”. I changed those to “a SQL...”. For example I changed “An SQL command which” to “A SQL command that”. I'm not an English major so maybe I'm missing something here.
  • I often thought “that” was easier to read than “which”, and there are several examples in the patch. For example “Space in data pages that…” replaced “Space in data pages which…”
  • Simplifications like: “There also exist two secondary forks” to “There are two secondary forks”

I was able to build the documentation locally and preview the HTML version.


If these types of changes are helpful, and can continue a consistent style through all the terms and provide a new (larger) v2 patch.



Thanks for taking a look.

Andrew Atkinson


Attachment

Re: [Doc] Glossary Term Definitions Edits

From
David Rowley
Date:


On Sat, 14 Oct 2023, 5:20 pm Andrew Atkinson, <andyatkinson@gmail.com> wrote:
  • Many examples of “an SQL”. I changed those to “a SQL...”. For example I changed “An SQL command which” to “A SQL command that”. I'm not an English major so maybe I'm missing something here.
It would depend on how you pronounce SQL.  For those that say es-que-el, "An" is the correct article. If you say sequel then it's "a". We've standardised our docs to use "an SQL", so any changes we make would be the opposite way. 

David

Re: [Doc] Glossary Term Definitions Edits

From
Erik Wienhold
Date:
On 2023-10-14 06:16 +0200, Andrew Atkinson write:
>    - When describing options for a command, changed to “option of” instead
>    of “option to”

I think "option to" is not wrong (maybe less common).  I've seen this
in other texts and took it as "the X option [that applies] to Y".

>    - “system- or user-supplied”, removed the dash after system. Or I’d
>    suggest system-supplied or user-supplied, to hyphenate both.

That's a suspended hyphen and is common usage.

>    - Changed “volume of records has been written” to “volume of records
>    were written”

"Has been" means that something happened just now.  This is perfectly
fine when talking about checkpoints IMO.

>    - Many examples of “an SQL”. I changed those to “a SQL...”. For example
>    I changed “An SQL command which” to “A SQL command that”. I'm not an
>    English major so maybe I'm missing something here.

Depends on how you pronounce SQL (ess-cue-el or sequel).  "An SQL"
is more common in the docs whereas "a SQL" is more common in code
comments.

-- 
Erik



Re: [Doc] Glossary Term Definitions Edits

From
Andrew Atkinson
Date:
> It would depend on how you pronounce SQL.
Got it, makes sense.

> We've standardised our docs
Makes sense. This "a vs. an" could be a nice thing to add to a "conventions" or "doc standards" if it's not there already. I checked https://www.postgresql.org/docs/current/notation.html and https://wiki.postgresql.org/wiki/Main_Page Is there a docs page that has that information? If there's an existing page where it could be added, I'd be happy to add it.

> That's a suspended hyphen and is common usage.
Sounds good, reset it back.

 > "Has been" means that something happened just now.
Sounds good, reset it back. "has been" is also used in the materialized term, "has been pre-computed".

> I think "option to" is not wrong
Ok, don't feel strongly. Reset it back.

> That's a suspended hyphen and is common usage.
Ok, reset it back.


Curious what people think about this. I thought the first phrase was possibly redundant.


-     On operating systems with a <literal>root</literal> user,

-     said user is not allowed to be the cluster owner.

+     The user <literal>root</literal> is not allowed to be the cluster owner.



I reviewed the definitions of assure vs. ensure, and I think ensure fits better, but I also noticed elsewhere the word “assurances” is used, as in an assurance about durability.  



-     makes it visible to other transactions and assures its

+     makes it visible to other transactions and ensures its



Re: that/which, I put this into ChatGPT :) and apparently there is a “relative clause” vs. non-relative clause. My understanding was a non-relative clause would typically be inside commas, and could be removed without changing the meaning.


Since this section is talking about Bloat, and the space in data pages with non-current row versions is part of bloat, I don’t think it could be removed. So I think it’s a “relative clause” and “that” makes more sense. 

This is another situation though where if there’s English majors or documentation experts, I’m happy to learn why I’m wrong. :) 



-     Space in data pages which does not contain current row versions,

+     Space in data pages that does not contain current row versions,




Smaller patch attached!

Thanks.






On Sat, Oct 14, 2023 at 12:55 AM Erik Wienhold <ewie@ewie.name> wrote:
On 2023-10-14 06:16 +0200, Andrew Atkinson write:
>    - When describing options for a command, changed to “option of” instead
>    of “option to”

I think "option to" is not wrong (maybe less common).  I've seen this
in other texts and took it as "the X option [that applies] to Y".

>    - “system- or user-supplied”, removed the dash after system. Or I’d
>    suggest system-supplied or user-supplied, to hyphenate both.

That's a suspended hyphen and is common usage.

>    - Changed “volume of records has been written” to “volume of records
>    were written”

"Has been" means that something happened just now.  This is perfectly
fine when talking about checkpoints IMO.

>    - Many examples of “an SQL”. I changed those to “a SQL...”. For example
>    I changed “An SQL command which” to “A SQL command that”. I'm not an
>    English major so maybe I'm missing something here.

Depends on how you pronounce SQL (ess-cue-el or sequel).  "An SQL"
is more common in the docs whereas "a SQL" is more common in code
comments.

--
Erik
Attachment