doc: consolidate use of multiple-byte units #42587
Conversation
|
Review requested:
|
nodejs-github-bot
added
lib / src
aduh95
added
author ready
github-actions
bot
removed
the
request-ci
|
Similar: #35051 |
|
I may be behind the times on what abbreviations we can expect people to be familiar with, but I think this is going to confuse people more than enlighten them. Also FWIW the style guide doesn't seem to recommend this. https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/bits-bytes-terms |
That's likely true. For memory sizes, for example, GB almost exclusively means base 2 anyway, whereas things are vastly different for data transmissions etc. |
|
I agree. Anyway, this PR LGTM if we want to use those units. |
|
I'm further confused by people both approving this PR and agreeing that it is likely to increase confusion. |
|
Lol. You are definitely right. I meant to say that the code changes look fine and we could definitely land this to improve docs(up for me on this). But, at the same time, the possible confusion is definitely worth a second evaluation (in contrast to handle this like a trivial doc fix PR). Hope this rant was understandable :) |
|
My take on this is we should use the technically correct units in our code and comments, I think it's fair to assume that most folks who would read it would not be confused by them. |
|
The standard that defined KiB as the abbreviation for 1024 bytes also says that the unit is a kibibyte and not a kilobyte (which is 1000 bytes, according to the standard). I don't think any of this is at all widely adopted and I'm not sure I want Node.js docs to be an early adopter for this type of thing, especially when "early adopter" means doing it after 15 years of no significant adoption of the terms. This from 2009 still seems to be the case: [Why does Explorer use the term KB instead of KiB?}(https://devblogs.microsoft.com/oldnewthing/20090611-00/?p=17933):
|
I don't love it, but it does have the virtue of precision. Another option is to always use bytes: |
|
(All my cranky comments are non-blocking. I just want these things considered before we land.) |
tniessen
dismissed
their stale review
I'm further confused by people both approving this PR and agreeing that it is likely to increase confusion.
|
I'm all for favoring correctness where it matters, and especially in scientific writing, I try to consistently use IEC symbols (KiB, MiB, etc.). That being said, according to the reference @aduh95 provided, using the unit symbols KB, MB, etc. for base-2 units is not incorrect but merely legacy:
|
|
Another possibility (that might not always be practical) would be to use the common/"legacy" abbreviations but precise byte counts for clarity: |
|
I like this one. |
|
Given that this PR has enough approvals + wait time, I'm down to land it as it, and to improve on follow up PRs. FWIW I'd be disappointed if we had to settle on using the legacy units, but as long as we remove the confusion of when we're using metric and when we're using base-2, I'm fine with it. |
|
Landed in 1e76165 |
Refs: https://en.wikipedia.org/wiki/Byte#Multiple-byte_units PR-URL: nodejs#42587 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Darshan Sen <[email protected]> Reviewed-By: Paolo Insogna <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Mestery <[email protected]>
Refs: https://en.wikipedia.org/wiki/Byte#Multiple-byte_units PR-URL: #42587 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Darshan Sen <[email protected]> Reviewed-By: Paolo Insogna <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Mestery <[email protected]>
Refs: https://en.wikipedia.org/wiki/Byte#Multiple-byte_units PR-URL: #42587 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Darshan Sen <[email protected]> Reviewed-By: Paolo Insogna <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Mestery <[email protected]>
Refs: https://en.wikipedia.org/wiki/Byte#Multiple-byte_units PR-URL: #42587 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Darshan Sen <[email protected]> Reviewed-By: Paolo Insogna <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Mestery <[email protected]>
Refs: https://en.wikipedia.org/wiki/Byte#Multiple-byte_units PR-URL: #42587 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Darshan Sen <[email protected]> Reviewed-By: Paolo Insogna <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Mestery <[email protected]>
Refs: https://en.wikipedia.org/wiki/Byte#Multiple-byte_units PR-URL: #42587 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Darshan Sen <[email protected]> Reviewed-By: Paolo Insogna <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Mestery <[email protected]>
Refs: https://en.wikipedia.org/wiki/Byte#Multiple-byte_units PR-URL: nodejs/node#42587 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Darshan Sen <[email protected]> Reviewed-By: Paolo Insogna <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Mestery <[email protected]>
Refs: https://en.wikipedia.org/wiki/Byte#Multiple-byte_units