Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Standardize usage of compound words, and document standards in docs style guide #10218

Open
tetrapod00 opened this issue Nov 6, 2024 · 3 comments
Labels
area:about Issues and PRs related to the About section of the documentation and other general articles area:contributing Issues and PRs related to the Contributing/Development section of the documentation area:manual Issues and PRs related to the Manual/Tutorials section of the documentation content:proofreading Issues and PRs related to proofreading the documentation enhancement

Comments

@tetrapod00
Copy link
Contributor

tetrapod00 commented Nov 6, 2024

Your Godot version:
4.4
Issue description:
There are some compound words, like "antialiasing", that appear in the docs in both hyphenated form "anti-aliasing" and in single-word form "antialiasing". For consistent style, we should choose one form and standardize.

Some examples:

  • antialiasing / anti-aliasing
  • runtime / run-time
  • screen space / screen-space
  • builtin / built-in / built in (this one depends on context)
  • subsurface / sub-surface
  • subemitter / sub-emitter
  • standalone / stand-alone
  • low-level / low level
  • high-level / high level
  • low-end / low end
  • addon / add-on (this one shows up in editor UI and in the res://addons/ folder, too!)

Resolved and standardized (within the manual):

  • Use "antialiasing", not "anti-aliasing". Added to codespell dictionary.
  • Use "runtime", not "run-time". In specific cases, "run time" is okay.
  • Use "built-in" as an adjective or noun, "built into" as a phrase. Avoid "built in" or "builtin", and avoid "built-in to".
  • Use "low-level", "low-end", "high-level", "high-end" as adjectives.

This is a fairly low priority issue. We should not break translations just to change this. However, we should choose which form to use for each compound word, document that choice in the style guide, and change existing usages whenever other changes are being made.

There's also precedent in #3502, #6978 of applying changes like this all at once.

URL to the documentation page (if already existing):
The whole manual and class reference.

@Mickeon
Copy link
Contributor

Mickeon commented Nov 10, 2024

Bit of a side note, we've broken translations for much less. I think going into a big pass for this is somewhat justified. I find consistency to be very important even for subtle details like these.

@tetrapod00
Copy link
Contributor Author

tetrapod00 commented Nov 10, 2024

I've been doing the manual changes one word at a time in multiple individual PRs. When that's done (or at least once we have a comprehensive list of compound words), maybe we can collect them and do the class reference changes in a single big PR?

@Mickeon
Copy link
Contributor

Mickeon commented Nov 10, 2024

Sounds fine by me.

@tetrapod00 tetrapod00 added area:about Issues and PRs related to the About section of the documentation and other general articles area:manual Issues and PRs related to the Manual/Tutorials section of the documentation area:contributing Issues and PRs related to the Contributing/Development section of the documentation content:proofreading Issues and PRs related to proofreading the documentation labels Nov 14, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area:about Issues and PRs related to the About section of the documentation and other general articles area:contributing Issues and PRs related to the Contributing/Development section of the documentation area:manual Issues and PRs related to the Manual/Tutorials section of the documentation content:proofreading Issues and PRs related to proofreading the documentation enhancement
Projects
None yet
Development

No branches or pull requests

2 participants