> 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.
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.