Discussing a "godot-docs" style guide and several instances of somewhat off-putting writing

[ghost]

I've been learning Godot and going through the documentation tutorial under the "step by step" section. I do notice, though, that some of the grammar, placement of punctuation, and sentence structure feels somewhat "off" when read by a native English speaker such as myself, as if it was written by contributors with a near-native understanding of English but without the experience to detect every edge case that comes from writing at length.

Some examples from the scripting section would be:

Actually, in GDScript, the file itself represents the class, so in this case, the class name field is not editable.

Most of the time you don't want that many commas in a single sentence, as every comma reduces your reading speed (or "flow") and putting too many of them in a row makes the sentence harder to understand due to the pauses that naturally occur while reading commas. I would remove the "Actually," as well as the comma after "case".

Note: A common misunderstanding in this tutorial is how get_node(path) works.

This sentence is vague; it can mean that the tutorial itself misunderstands how "get_node(path)" works, or the reader misunderstands. I would rephrase it as "A common misunderstanding when reading this tutorial..."

GDNative / C++ Finally, this is one of our brightest additions for the 3.0 release. GDNative allows scripting in C++ without requiring to recompile (or even restart) Godot.

Saying that "this is one of our brightest additions" is a bit redundant when the header already shows what the addition is, being GDNative. The second sentence uses "requiring" when most writers would use "requiring you", "needing", or "having" (less formal than "needing"). I would also phrase the first sentence as "Finally, one of our brightest...". These suggestions sound more "natural" in English, but there's no scientific definition for what sounds natural, so you'll just have to trust me on that 🙂

I know it sounds petty to nitpick like this, but when you see a lot of small issues over the course of several pages worth of documents, it adds up to make a jarring experience for the reader.

The solution:

The solution to the above would usually involve making fixing up the page and pushing an edit to it, much like Wikipedia. Unfortunately the GitHub model of needing to approve every pull request leads to a bureaucracy where maintainers would argue over minor details with the pull requester and would either reject the request or have to wait significant amounts of time in order for the requester to edit their contribution.

So instead of bickering over who has the best idea of how the documentation should be written, it would be nice to develop a style guide for contributors, so that we can all agree on the best way to write for the Godot documentation and reference the guide for all of our writing style disputes.

Such issues could include:

• When to capitalise letters and add periods at the ends of lists.
• How best to use italic and bold-faced text.
• Whether to use semantically-correct versions of iconographs - e.g. -> converted to →, or "..." converted to "…" (the first one is three periods, the second one is an ellipsis).
• Whether "etc." should have a period inside parentheses (such as: etc.).
• When UI elements should be capitalised, if at all, and how to capitalise them (such as "Play button", "PLAY SCENE", and "'TEXT' Property").
• Standardised spelling and grammar, which I believe is now American English per #1066.

Do understand that I'm not a professional writer as such, though I have written books that people have bought, and have founded three different websites (very silly and often vulgar sites) that helped me write about 500,000 words during 2017 alone. This is just my personal GitHub account, and those are just my personal blogs, so the level of scrutiny on them are obviously much less than for contributing to Godot.

• Standardised spelling and grammar, which I believe is now American English per #1066.

Do understand that I'm not a professional writer as such, though I have written books that people have bought, and have founded three different websites (very silly and often vulgar sites) that helped me write about 500,000 words during 2017 alone. This is just my personal GitHub account, and those are just my personal blogs, so the level of scrutiny on them are obviously much less than for contributing to Godot.

Do understand that I'm not a professional writer as such, though I have written books that people have bought, and have founded three different websites (very silly and often vulgar sites) that helped me write about 500,000 words during 2017 alone. This is just my personal GitHub account, and those are just my personal blogs, so the level of scrutiny on them are obviously much less than for contributing to Godot.

[mhilbrunner]

I agree that this is an issue, but I don't follow your conclusion.

Your conclusion seems like it could be summarized (a little unfairly) like this:

1. Godot docs have issues
2. Improving them is hard because [reasons]
3. Therefore, lets create a style guide stating what should be and hope somebody else does the work

This won't work. A style guide may help but it won't magically fix those issues. These issues exist because:

1. Many contributors aren't native speakers
2. Many contributors aren't professional technical writers
3. There are not enough contributors

And this isn't only the case for grammar, style and spelling. Content-wise, a big portion of the docs could be improved and updated too. Entire sections and pages that should be there are missing.

The only way to fix this is to actually fix it. This requires work. Work that surely could be supported by a style guide, but still: work.

So please, point out all of those issues. Not only examples, point all of them out wherever you find them. Create issues for them. Even better, fix them and submit Pull Requests.

Unfortunately the GitHub model of needing to approve every pull request leads to a bureaucracy where maintainers would argue over minor details with the pull requester and would either reject the request (…)

Is this speaking in general terms or specifically for past experiences with godot-docs? In my experience, getting docs writing improvements merged is mostly painless and doesn't take much time.

Case in point: I agree with all issues you pointed out and would be happy to merge a PR improving those.

But if this is the case it should be discussed and improved.

Do understand that I'm not a professional writer as such

Do kindly understand that you may be both overestimating the "the level of scrutiny" for "contributing to Godot" docs and underselling yourself. You already seem to have way more experience writing than many, if not most documentation contributors. Way more than me at least. Again, keep in mind that most of us aren't native speakers and software developers first, docs writers second... or third. :)

So if you feel you could help out, please do.

[vnen]

While I agree that guidelines are good for consistency (especially about the formatting), someone has to do something, and that's the hard part (as @mhilbrunner stated). Essentially:

1. Propose an actual list of guidelines.
2. Discuss a bit with the current maintainers to reach a consensus.
3. Implement the guidelines by change all pages that break them.

I understand the reasoning and agree that the documentation has some flaws but this kind of issues usually stays hanging unless the proponent is willing to do something. I'm not dismissing the issue, but it's the reason why the main repository has over 2700 issues: a lot of heads with ideas, not enough hands working.

Also: it's unfair to compare with Wikipedia because 1) it is huge, 2) all of it is text (unlike Godot which is a software first), so obviously text quality is a main point, and 3) it's heavily moderated. You can argue it's easier to change text in Wikipedia, but it's also easier for someone else to quickly revert the modification. There's a lot of "bickering" over there.

[ghost]

@mhilbrunner Alright, I'll make some pull requests as I see issues as I perceive them. My main concern in doing so is being trusted that what I contribute is fair and accurate, and to make sure that what I contribute is uncontroversially better than the state of the page before it.

@vnen Most of my personal philosophy comes from Matthew Butterick's "Practical Typography" and Robert Bringhurst's "The Elements of Typographical Style". I'll make some propositions tomorrow when I'm more refreshed, though I encourage a readthrough of Practical Typography.

Do understand I'm not trying to lazily outsource work, it's just that all my experience with free culture projects in the past have been negative due to exclusionary and insular nature of them, and the mentioned bureaucratic nigglings that I find stops progress until everyone agrees with each other.

[NathanLovato]

Note there are writing guidelines inspired by the Chicago manual of style. Non-natives and natives often need help to understand issues like writing passive sentences all the time. Some of the docs were written or proofed by natives.

In this repo fixes get merged pretty fast as long as they help to simplify, clarify, or clean up the docs. Proofing, rewriting stuff... it's all welcome. Unlike the engine's repository the commit history isn't too important here so you can send PRs fast. Compared to blogging the only thing I tend to ask as a reviewer is that everyone tries to use simple words and reasonably long sentences when possible. We're writing for people from all around the world after all.

[ghost]

@NathanLovato @vnen @mhilbrunner After going over the Godot documentation and numerous style guides for about five hours, I’ve created a conglomeration of basic ideas that aims to reconcile the petty inconsistencies that I’ve noticed in the documentation. I’ve cast aside traditionalism in favour of focusing on modern technical writing, and therefore does not tell contributors how to write, but how to proofread what they have already written.

I hope that agreeing on a style guide such as this will create a more consistent and readable introduction to anybody’s first time with Godot.

“godot-docs” style guide proposition

Punctuation

• Word pairs should be hyphenated, such as “high-level”, “double-breasted”, and “open-source software.” This prevents ambiguous meanings, such as “five-dollar bills” and “five dollar bills”. The first means an arbitrary quantity of bills worth $5. The second means five $1 bills that add up to $5 total.

• Ampersands should not be used, except for “Q&A” and in code examples.

• Links don’t need quotation marks around them, except for when they would need them normally.

• Writers should “avoid overpunctuating lists” (Bringhurst 4.4.2), as “speakers reciting lists often enumerate on their fingers, and lists set in type often call for equivalent typographical gestures.” In brief, writers should use their best judgment for punctuating lists. Long sentences should have periods at the end, non-sentences don’t need them, and they should always be capitalised at the start. Lists should be used to enhance clarity, but not replace prose. A handy reference is at http://www.ossweb.com/article-bullets.html .

• Punctuation should come after words in parentheses, the first letter should be lowercase, and parentheses should never replace full sentences. For example:

  • The convicts escaped (as they tend to do),
  • The convicts escaped, as they tend to do,

• But not:

  • The convicts escaped, (As they tend to do),
  • The convicts escaped. (As they tend to do).

• Periods should go inside quotation marks instead of after them, as is the American way. For instance, “Selfish High Heels.” instead of “‘Selfish High Heels’.” See https://www.grammarbook.com/punctuation/quotes.asp .

• Use "straight quotes" instead of “curly quotes” when editing pages. Some keyboards, like “US international with dead keys”, offer both, though straight quotes are already converted to curly quotes on the documentation and manually inserted quotation marks are hard to maintain. The same goes for 'straight apostrophes' instead of ‘curly apostrophes.’

Spelling and capitalisation

• Use American English. I use Wiktionary to determine best use, such as “judgment” instead of “judgement.”

• UI elements should be capitalised the same as they are in the UI. For instance, “Gravity Scale”, “FileSystem”, and “Debugger”, but not “scene”, “node”, or “editor.”

• Headings should have their first word and proper nouns capitalised; nothing else. Title case shouldn’t be used for the fact that headings aren’t titles.

• Words should be updated to their most modern form, such as “email” instead of “e-mail”, “runtime” instead of “run-time”, and “hard drive” instead of “hard disk.”

• Jargon should be avoided when possible in favour of clear prose, such as replacing “save to disk” with “save to your computer”, or just “save.”

• “node” and “scene” should be made lowercase. “Free” should be capitalised when it’s Free as in Freedom. “2D” and “3D” should always be uppercase. And “etc.” should always have the period, as it is an abbreviation of “et cetera.”

• Remember to spell “GitHub”, not “Github.”

Typography

• Use tabs instead of spaces to be consistent with the Godot indenting style. I don’t know if the website compiler accepts tabs, but it should at least be used for the code examples.

• Proper headings should be used, instead of bold text with space underneath it.

• When using bold or italic, bold or italicise the punctuation after it, such as “soon,” or “common-place,” but not for parentheses, quotation marks, or other encompassing punctuation.

• Parentheses should not adopt bold or italic text, except for when italic text within parentheses collide with them (see https://practicaltypography.com/parentheses-brackets-and-braces.html).

• Never use bold and italic at the same time, and avoid them in quotation marks and parentheses, especially at the beginning and end. “The power is in his hand” is alright, but not “The power is in his hand.”

• Never use underlines, as these will be confused as links.

• When to use code tags:

  • Filenames
  • File extensions
  • Arguments
  • Properties
  • Numerical values for properties
  • Coordinates
  • Scene names
  • Node names
  • Keyboard shortcuts
  • Code examples

• When to avoid:

  • Combined with links
  • UI elements (use quotes as necessary)

Symbolic replacements

• Use proper ellipses instead of three periods. Many typefaces render “...” (three periods) and “…” (ellipsis) differently, especially monospaced fonts.

• Use en dashes (—) instead of hypens (-) for non-code text. For instance: “This dog — or is it a dog? — …” and not “This dog - or is it a dog? - …)

• Proper symbols should be used instead of their approximations. For example, “→” instead of “->”, 800×450 (dimension sign) instead of 800x450 or 800*450, and © instead of (c).

• Math symbols should be used instead of approximations, except in code examples. Use × instead of *, ÷ instead of /, and − (minus sign) instead of - (hyphen). They should have one space in front of each symbol, such as “(4 × 6) ÷ 2 − 4 = 8.”

[mhilbrunner]

@gemkibeju Thanks for investing work in this. :) Looks reasonable after a first read, and already contains some things that will help me in the future when reviewing both my work and that of others. Let's wait and see what the other docs people think and say, but this looks like a good start. If we agree on this, we should merge this with the existing guidelines.

Note that many Godot contributors are currently in Brussels for FOSDEM and GodotCon, so things may take a little longer than usual. :)

[RiverMesa]

My only gripe with the symbolic replacements is that on many keyboard layouts, they can be an absolute pain to actually insert, especially when it'll have to be done often (as it will).

This could probably be helped by keeping a chart of the most common-yet-not-proper symbols, their approximations, and their Unicode codepoints, so that they can be used to create substitution definitions (similar to how it's done with images) in the RST documents. (See this.)

Symbol	Approximation	Unicode codepoint
— (en dash)	- (hyphen)	U+2013

I think this is preferable to forcing people to learn how to insert all sorts of non-ASCII characters, which varies from OS to OS and may also be screwy in other ways.

Other than that, a pretty solid set of guidelines IMO.

[ghost]

@RiverMesa I keep a text file with dashes and an ellipsis on my computer. For em dashes it's easy enough for me to:

1. Find “ - ”
2. Replace it with “ — ”

But with technical documents the big issue is with removing valid code and replacing it with invalid code. Same for all my other suggestions; in regular work it's easy enough for me to go back and grep “...” instead of “…”, but not so with a markup language like RST. So that's I listed them under a separate section; they're good for semantic correctness and for proper typography, but they aren't strictly necessary.

One other note: I've noticed a lot of pull requests coming from the headings on RST being off by several marks, for instance:

Handling a signal
~~~~~~~~~~~~~~~

In a non-monospaced font, it's impossible to tell how many tildes you need to fully underline the heading, because the character widths are different from a monospaced font. Would it be easier to only use a set amount of tildes, say four or five, instead of having to fix them all individually?

[RiverMesa]

The problem is that then Sphinx complains about the amount of tildes not being perfect compared to the amount of characters (incl. spaces) in the titles.

I believe it's merely warnings rather than build-breaking errors, but still.

[mhilbrunner]

I plan to fix the big bunch of warnings for the current content after GodotCon :)

[NathanLovato]

Thanks for your detailed feedback!

Let's add @cbscribe and @akien-mga. Can you check these suggested guidelines from @gemkibeju real quick ?

It makes sense and it'd certainly make for cleaner docs overall. Now we can't expect the majority of contributors to apply all these as a handful writing guidelines are already a lot to take on for many of us. A fair part of the existing content was also written by people whose English is a bit limited and a long time ago. Most of docs contributors don't have a ton of writing experience. We're only a handful to have done this professionally.

To add all these improvements I guess we could save time using some kind of linter and script anyone could use. Something like proselint can already help. I'm sure there's some existing tool we could leverage to save a lot of review time: checking sentence length, replacing 2d or 2-D with 2D, etc. Same thing with using the right symbols.

Use tabs instead of spaces to be consistent with the Godot indenting style

Godot supports and uses both. Sphinx converts to spaces and I think it only supports this as its designed with Python in mind initially. Not sure tab-based indents are possible at all.

Would it be easier to only use a set amount of tildes [...] instead of having to fix them all individually

As @RiverMesa said it's a warning, and that's how the RST syntax works. We don't have control over this. Maybe it's possible to deactivate the warnings though? It still converts so it's not important.

[ghost]

On reflection, I believe it may be difficult to remember all that I wrote here, as most style guides tend to be too long to make full use out of. Perhaps it would be best to remove some common-sense suggestions from the guide, such as only using straight quotes?

[Calinou]

Closing, as we now have Docs writing guidelines.