raspberrypi / style-guide

14 stars 11 forks source link

Update storage and transfer size units to SI standards #33

Closed nathan-contino closed 3 months ago

nathan-contino commented 3 months ago

paging doctor @Wren6991 for a sanity check. Decided to include all of the vaguely popular and reasonable options for clarity, but if we really want to omit any of these, let me know. The descriptions provide guidance to avoid certain terms except for rare cases (and point readers to the most likely replacement term).

Wren6991 commented 3 months ago

So the summary of the change is: engineer-facing writing uses SI units and prefixes, plus the IEC convention for power-of-two prefixes. Looks good to me. The only thing I might add is a note to not use kiB (correctly rendered as KiB) because I have been guilty of this mistake.

The other issue mentioned in copy edit reviews with @nathan-contino is the use of commas as digit separators in large numbers. These can be ambiguous because most of Europe uses commas for the decimal point, so 100,000 could mean "one hundred thousand" or "really precisely one hundred", depending on locale. This may be another case where we decide use based on audience -- I agree the comma has a more comfy vibe.

lurch commented 3 months ago

These can be ambiguous because most of Europe uses commas for the decimal point, so 100,000 could mean "one hundred thousand" or "really precisely one hundred", depending on locale.

I remember being very confused by this (many years ago!) when I first went into a shop in Europe :joy: But (in most everyday usages) the thousands-separator tends to have three digits after it, and the decimal-separator tends to have two digits after it (especially when referring to currency amounts).

Wren6991 commented 3 months ago

But (in most everyday usages) the thousands-separator tends to have three digits after it, and the decimal-separator tends to have two digits after it (especially when referring to currency amounts).

The real reason I raised this is "NIST recommends it", I just wanted to provide some motivation. See here: https://www.nist.gov/pml/special-publication-811/nist-guide-si-chapter-10-more-printing-and-using-symbols-and-numbers

image

The current style guide is not wrong, it's just counter to common practice for technical documentation and academic literature, so I thought it might be worth allowing some discretion based on audience. I'm happy to spin out a separate issue if I''m derailing this one

nathan-contino commented 3 months ago

@helenlynn I think we're good to merge! Please merge this when you get the chance. And if you can finally grant me merge permissions for the style guide, even better if I can merge it myself!