Обсуждение: [Doc] Glossary Term Definitions Edits
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
Вложения
- 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.
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
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,
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