[Writing] Add guidelines for formatting numbers - #107
Conversation
|
CC @Meorge I think it was with you I discussed this previously |
Meorge
left a comment
There was a problem hiding this comment.
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.
da4ea2e to
78fd369
Compare
Mickeon
left a comment
There was a problem hiding this comment.
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.
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)
Please read it again, it doesn't say that |
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