Skip to content

[Writing] Add guidelines for formatting numbers - #107

Open
AThousandShips wants to merge 1 commit into
godotengine:mainfrom
AThousandShips:writing_format_numbers
Open

[Writing] Add guidelines for formatting numbers#107
AThousandShips wants to merge 1 commit into
godotengine:mainfrom
AThousandShips:writing_format_numbers

Conversation

@AThousandShips

Copy link
Copy Markdown
Member

The specifics is open for discussion and not entirely sure where to place this.

Based on discussion while proofreading the release page for 4.7

@AThousandShips
AThousandShips requested a review from a team August 6, 2026 12:55
@AThousandShips AThousandShips added the enhancement New feature or request label Aug 6, 2026
@AThousandShips

Copy link
Copy Markdown
Member Author

CC @Meorge I think it was with you I discussed this previously

@Meorge Meorge left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the CC! I think I may remember the conversations about this as well 😄

Overall I think it looks and sounds good. There's a few small changes/typos I noticed, and then a couple points that might be good to discuss or incorporate, but may also be unnecessary.

Comment thread documentation/guidelines/docs_writing_guidelines.rst Outdated
Comment thread documentation/guidelines/docs_writing_guidelines.rst Outdated
Comment thread documentation/guidelines/docs_writing_guidelines.rst Outdated
Comment thread documentation/guidelines/docs_writing_guidelines.rst Outdated
Comment thread documentation/guidelines/docs_writing_guidelines.rst Outdated
@AThousandShips
AThousandShips force-pushed the writing_format_numbers branch from da4ea2e to 78fd369 Compare August 6, 2026 15:14

@Mickeon Mickeon left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To be honest, and this is kind of surprising coming from me, I find this new section to quite the nitpick. I don't see much benefit in this as it's currently written.

First of all, all that is described in this PR is generally common writing knowledge. I can personally say I got it taught these rules in the first grades.
Of course that's not everyone's background, but one starts to pick up on these rules almost instinctually. And I believe we can help with that, because...

The documentation doesn't really have a severe problem with number formatting. In fact, given the background of most users, most would write numbers as digits, anyway.
I understand that this PR aims to explain the opposite case better (that is, numbers in plain text) but the situations were they would be more appropriate are much rarer in the docs.

  • I have never seen the "1000s" construct ever in the documentation. Not only it looks instinctually out-of-place, but I'd argue most would be inclined not to give inexact numbers, anyway, and instead say "many", "a lot of", "several", etc.
  • Unlike what the PR suggests, in our rather technical documentation, I don't personally think it's that bad to use digits all the time.

I'm not going to "block" it, but I don't agree with adding this to an already rather long and hard-to-follow page.

In fact, given that the original discussion derives from the 4.7 release page PR (although I'm sure there were a few more "catalysts"), it suggests that we need a page about... writing, in general. Some standards from the documentation writing guidelines can (and have been) transferred over, sure, but I don't really think this deserves to be here.

@AThousandShips

AThousandShips commented Aug 6, 2026

Copy link
Copy Markdown
Member Author

First of all, all that is described in this PR is generally common writing knowledge.

I disagree, this was discussed at length in the blog post and wasn't clear or obvious to everyone, it also hasn't been clear in review for some users, see for example the recent update to the GDScript basics page, so this is clearly not obvious to all

Also a lot in this page would fall into that, like how to format the genitive, and how to use oxford comma, most people who write the documentation are not native English speakers (and many don't even write numbers as is done in English)

Unlike what the PR suggests, in our rather technical documentation, I don't personally think it's that bad to use digits all the time.

Please read it again, it doesn't say that

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants