Add hyphens to adjective phrases

[JohnVeness]

Hi. I have done some searching and replacing within the docs, adding hyphens where grammatically correct, that is, when something is used as an adjective ("open-source license") versus a noun ("Godot is open source"). Hope this is welcome!

[AThousandShips]

This being a minor language quirk and nitpick makes it important to consider the impact on translations as this will invalidate existing translated content

[skyace65]

In addition to what AThousandShips said "Open-Source" doesn't seem to actually be grammatically correct. it's written "open source" without hyphen on wikipedia as well as the Red Hat website.

[JohnVeness]

"Open-source" when it's an adjective, not a noun. E.g. https://en.wikipedia.org/wiki/Free_and_open-source_software

[tetrapod00]

I'm generally in favor of these kinds of hyphenation standardizations for the docs (see #10218), so I'm not per se opposed to this. However, it's better to start from existing usages and standardize, rather than choosing the form that is most correct in the abstract.

In the current manual (excluding the class ref pages):

• "open-source" is used 3 times, "open source" 42 times. This one I don't think makes sense to change even if it's technically wrong.
• "cross-platform" 4 times, "cross platform" 3 times. Sure, change this.
• "command-line" 19 times, "command line" 107 times. I don't know about changing this one.
• "platform-specific" 11 times, "platform specific" 3 times. This one makes sense to change

I'm not sure if this is an exhaustive list of the phrases you checked, just took a cursory look. Seems like adjective phrases that only exist as adjective phrases are good candidates to use hyphens for, but adjective phrases that also exist as nouns perhaps not. The number of files affected is also a factor.

I actually did change some of the "built in" instances you found to "built-in" in #10235. Note that Godot uses "built-in" as a noun quite often in place of the full form "built-in variable".

I'd suggest maybe making another PR (or a few split PRs) for the less controversial set of changes here (everything that isn't "open source" or "command line".

[mhilbrunner]

I agree with what was discussed here. Closing as per the above. Also, if we are going to make (a subset of) these changes, we should keep them to master to release in the next version, although even then breaking translations for this isn't the best.

Thanks for taking the time to contribute and add all these hyphens, even if we're not going ahead with this :)

[JohnVeness]

Thanks for all the notes above. If I do decide to suggest similar changes again, I'll likely break it down into single words, to make it easier to accept/reject a PR.

I like the look of @tetrapod00's work in #10218 and related PRs. Apologies if I've overlooked one, but it would be great if there was a Godot documentation style guide, such as the Raspberry Pi one at https://github.com/raspberrypi/style-guide/blob/master/style-guide.md

[tetrapod00]

Hey, @JohnVeness, I went ahead and extracted out the improvements which I think have a good chance of being merged into two new PRs (#10284 and #10285). You're listed as the co-author on the commits.

As for the style guide, there is one here https://docs.godotengine.org/en/latest/contributing/documentation/docs_writing_guidelines.html. I just made some improvements to it in #10169. I have some more ideas to add to it, but wanted to get some more experience with actually making changes before prescribing too many subjective standards like hyphenation.

As for why we don't have more comprehensive prescriptive style guide, I believe it's been discussed in the past (especially in #1084, #5932) and the conclusion was that even if we had one, it would be difficult to enforce with contributors who are largely not technical writers, and are often one-time contributors. I personally still think there are some useful standards to extract from that issue that are not currently documented or enforced, but I'm starting by making the changes in the docs themselves rather than starting with a prescriptive style guide.

[JohnVeness]

Thanks for picking this up and submitting the subset PRs. And thanks for pointing me to the existing style guide, and for your work improving it.

I agree that it can be hard to enforce a style guide, and I think "enforce" is too strong a word anyway! I'm very happy for non-technical writers to write documentation within their abilities and for other people to proofread/edit it later if necessary. It's just that without such a style guide, different people might have different ideas about (or might just plain forget!) what typical changes should be made.

[tetrapod00]

Yeah, I think my ideal outcome with a detailed style guide is that we have a short version that we expect most casual contributors to read and apply as best they can, and also a long detailed one which we expect maintainers to read and remember at least some of. Casual contributors can read it if they wish. During review, suggested changes can optionally come with links to the relevant sections of the style guide.

There's also #10170 which is a potential implementation of a short summary of docs contributions guidelines, though I'm not sure if it's the best format for such a thing.