[Docs] Add some English quirks

[AThousandShips]

A few common errors I see when doing review that deserves mention.

[Mickeon]

Amusingly "quirks" has been misspelled within the PR itself

[Mickeon]

What if you were to mention proper usage of - in the middle of words, as well? There's a rule to it, but even English speakers often do not think about it.

Can't think of any examples right now. Too busy with localization.

[Mickeon]

Good to know the name of these.

We may want to genuinely discourage noun adjuncts in the near future. We contributors use it a lot. As programmers, we write the docs most similarly to how we speak, via shorthands. The problem is, this results in some combination of words that are genuinely incomprehensible for first-time readers, or worse, completely unreadable for localization purposes.
Of course, you know as well as me that there's plenty of situations where they make text easier to digest, if used appropriately.

[AThousandShips]

That would be a very odd restriction, very unnatural use of English IMO, and having "list of nodes" might not be very cumbersome there would be far more awkward constructions otherwise

If you have any good examples of cases where it hurts readability that would be good to look into, but I can't think of any, you'd have "the transforms of nodes that are children of this node" instead of "the child node transforms"

[AThousandShips]

Node adjuncts are common in various languages as well, it's not just a thing in English

[Mickeon]

To be honest, finding actual examples for me is difficult, because I've gone through many of them and attempted to fix them manually in my language, personally.

But I guess as short examples (albeit weak ones, as the topic is very advanced), here's the following from RDFramebufferPass and RenderingDevice's documentation

"Framebuffer pass attachment description"
"Pipeline color blend state attachment"
"Maximum vertex input attribute offset"

In these descriptions, the most layman way to decompose this series of words would be, for example, "Description of attachment of pass of the framebuffer". There is no exact correlation or way to infer how exactly these terms are related with one another, they just are. Of course, it may be possible to infer it from the surrounding context, but not always, let alone for any reader outside of the field of expertise.
To be clearer, potentially stacking multiple noun adjuncts is what is particularly problematic here. They make the relationship between words vague and way too up to interpretation.

[AThousandShips]

That would be a good example of ones to break up a bit, but they are few and far between, each could be fixed by replacing one of the steps, I don't think "Description of the framebuffer pass attachment" is a problem, "description of the attachment of the pass of the framebuffer" is far too verbose IMO (skipping the definite article is ungrammatical here)

[Mickeon]

Okay, fine. Receipts, albeit opinionated ones. Keep in mind that these, by themselves, are not necessarily a problem, but when compounded by the aforementioned readability issues, they most certainly can be.
For example, I've seen both French and Spanish mistranslating some words because they're written this way. Again, finding concrete examples is very difficult after casually dealing with them manually.

• screen-space indirect lighting texture, screen-space ambient occlusion texture, ...
• "Sets scroll bar x range"
• "active keyboard layout index"
• "caret character offset"
• There's both "global illumination buffer" and "buffer used for global illumination". One of the two is clearly more meaningful while not being much longer.
• "table column name"
• "control width" is a case of misusing a noun adjunct, where it would be more appropriate to use the possessive s. I reiterate, there's miscellaneous cases like this around the documentation.
• "customize valid parameter range"
• "initial horizontal drag offset"
• "one-click deploy menu item label"
• "one-click deploy menu item label"
• "per-instance shader uniform names of the per-instance shader uniform from the specified canvas item instance"
• "navigation mesh surface point"
• "iOS application 64x64 icon file"

[AThousandShips]

I think these can absolutely be improved, but translations are probably more an expression of translations being done by people who don't know English well enough to perform translations in some cases, but still relevant to aid in that process as we can't assume high proficiency of translators necessarily

[Ivorforce]

Thanks!

[AThousandShips]

Thank you!