The Twitter bug in December 2014 was caused by using %G instead of %Y. So that won't help much. G comes before Y alphabetically, as does almost ant other letter...

But what is relevant is that the manpage explanation is still "precise but misleading":

http://manpages.ubuntu.com/manpages/cosmic/man3/strftime.3.h...

"The ISO 8601 week-based year (see NOTES) with century as a decimal number. The 4-digit year corresponding to the ISO week number (see %V). "

It's still misleading in the sense: "do we want ISO standardized year? Hell yeah! We've found what we want."

It induces all the wrong reflexes: is ISO datetime "the name of the most standard date format that can't be read wrongly? Yes. ( https://en.wikipedia.org/wiki/ISO_8601 ) Is it "ISO 8601"? Yes. Do we get "four digit" "decimal" year? Yes. Hm... it's "week-based"? "Well every year has weeks, so I guess it's all right." Has references to some other part of documentation, "that means that the details probably don't matter much here." Etc.

The proper documentation would be: "%G (short for "wronG in most use cases") returns the "week-number-based-otherwise-wronG-year" used only for the special number-of-weeks-based calendar representations, according to the ISO 8601 rules for such representations, and it only by accident sometimes looks like the common calendar year. Should not be used unless it's specifically needed to produce such a number-of-week-based calendar. For the details about these calendars see (the reference)."

In the later case the "don't touch this unless you know you need exactly this" is explicit. It even gives a good mnemotechnic device for remembering the "wrongness" of using it in most of the cases. Good documentation is really important, even if the "traditional" -n-x users feel some kind of satisfaction in having the most misleading or useless documentation, to the point that when somebody asks some specific question they point to the very man pages which exactly don't answer that exact question (there are many such examples on the web). And I've personally seen exactly these same self-satisfied programmers behaving just like the users they subconsciously (or consciously) mock, that is, being equally clueless, once they are in front of any other, probably even a bit better manual, but for the topics they are not familiar with. Like setting up a darned printer.

Being user hostile is never a virtue, and never something that should be supported or explained away.

You are omitting the requirement of common sense, or should I say discouraging it, and that is a dangerous path to go down. Almost all of the letters are strongly mnemonic. Someone who does not even think about what %y or %Y would be, after reading %G and thinking it correct, is going to have trouble with a lot of other things too.

> Someone who does not even think about what %y or %Y would be, after reading %G and thinking it correct, is going to have trouble with a lot of other things too.

I'm surely not questioning that specific claim that you make now. However, my major claim is:

Everybody is stupid, if he's not working in the area of his narrow specialty, and more than that, even those who are working in the areas familiar to them will not always have ideal circumstances in which they will use the manuals or the APIs. Therefore designing anything only for those who have infinite time and concentration to use your product is inherently wrong.

Specifically, I can imagine a person who under ideal conditions would spend some necessary days to learn all the details of that formats and date use cases and what not to have some other circumstances in which it has to produce some result fast or while distracted, and that other persons who are in charge to confirm what that person produced also fail to recognize the error, to the point that the subtly wrong implementation is eventually not properly tested. Which is what provably also happens in practice. And I also really saw the persons capable of learning and remembering a huge amount of all unnecessary (for me) switches for commands x, y, z, x1, y1, z1 etc, in some other, still not too stressful situation unable to eventually manage to install the mentioned printer on the same OS.

In the same sense, the writer of manual who spends days learning about all the features that he documents should not assume that his readers will spend the same amount of time or will have necessary conditions to figure out all nuances that were "obvious" to the writer at that specific moment. In fact the similar forces that produce buggy code are the ones that produce poor documentation.

So we should not try to excuse both bad code and bad documentation, but instead support the "empathy" for the possible less-than-ideal conditions of our users.

And I claim that the documentation obviously produced without understanding what most of the users need to be able to easily read from it is bad, and that it should be recognized as such.

> (see NOTES)

If you skip over this huge red flag, sure. "See notes", "see below" &c. are almost invariably a bad sign: they indicate that there's complexity here that's too long to explain in-line.

Reacting to that with "Hell yeah! We've found what we want." is beyond salvation.

No. What you put in “see notes” notes is the boring technical detail such as how week numbers are calculated and which document or paragraph this particular implementation holds authoritative over conflicting alternatives.

What you put in the man page is the clear statement that for example YYYY “week year” should not be used where yyyy “calendar year” would usually be more appropriate: point out the confusing alternatives and which one the unaware reader is most likely to need.

... overlooking the fact that you aren't sure what it means for a year to be week-based in the first place, since years aren't a part of a week and weeks don't fit evenly into years.

Literally the next sentence suggests that %Y is broadly similar, and that %G has exceptional cases:

> The ISO 8601 week-based year (see NOTES) with century as a decimal number. The 4-digit year corresponding to the ISO week number (see %V). This has the same format and value as %Y, except that if the ISO week number belongs to the previous or next year, that year is used instead. (TZ) (Calculated from tm_year, tm_yday, and tm_wday.)

The %Y text, by the way, is much shorter:

> The year as a decimal number including the century. (Calculated from tm_year)

I find it hard to fault the manual here; the only improvement I can see making is specifying that %Y is the calendar year, and perhaps noting that it is more appropriate when months are used. Of course, speople (e.g. GGP) feel that in this situation some condescension is deserved, and it may be true that what few users would be misled when they really do want to use a week-based year are more than outweighed by those who correctly choose to use %Y instead.

The objection to this isn't technical, because the perceived slight isn't technical. But there is a sentiment, more popular in some circles than others, that the user should be respected as a responsible adult who knows what they're doing, that the programmer using the interface is a peer, and that if they aren't, or are operating while impaired, it behooves them to realize this and either sober up or pass the buck. This isn't necessarily true. Sometimes, e.g. if the interface is exposed to end-users in a field for preferred date format on an invoice or something, it's totally inappropriate. But it is a somewhat traditional assumption, especially for ~system-level interfaces like strftime.

There’s also the issue of week-of-year calendars being useful for a very small niche, so it’s basically technical jargon of one speciality imposed on the rest of the world, the same way lawyers debate commas and treat and & or completely differently to sane people.

Familiarity with strftime is part of gaining experience in the field, and will usually involve using YYYY until it breaks and then finding articles like this one written over the last two decades explaining that you have tripped over a loose paver that everyone else in the industry already knows about (but at least now you understand why there are so many broken wrists).

There’s a similar problem in orbital mechanics where people try doing a calculation using Kepler’s equations, but because they’re using degrees they get the wrong result. Of course the equation is entirely in radians, which they quickly learn about but not before suggesting that the languages or APIs they are using need new features to help other people avoid falling into that trap.

You are not wrong. But everyone is stupid some of the time, and documentation should take that into account.

People complain a lot about PHP but it's not always horrible. Excerpt from the documentation:

o - ISO-8601 week-numbering year. This has the same value as Y, except that if the ISO week number (W) belongs to the previous or next year, that year is used instead. (added in PHP 5.1.0)

(https://secure.php.net/manual/en/function.date.php)

We had this problem a long time ago when asp was used. We really needed this Year-week numbering but it didn't work. It was hard-coded to 52 weeks per year and the year was the true year. Someone had to manually fix it every few years when it didn't add up.

In Java `x` is reserved for time zone offset: https://axibase.com/docs/atsd/shared/time-pattern.html#patte...

I thought you’re supposed to use Z for that? What’s the difference then?

There's an example column on the link, it has to do with the exact formatting of the offset.

Z is just shorthand for for offset +0.