Python docs disappointing

[Steven D'Aprano]

jstnms123 at gmail.com wrote:

> I write this to address the criticism which targets a user's lack of
> responsibility for the real/implied/insinuated failings of the docs.  As a
> relatively inexperienced student of programming, I am not in any position
> to contribute/edit the documents.  THAT DOES NOT, however, DENY THE
> CATEGORICAL STUPIDITY OF THE DOCUMENTATION: .  Not only are the semantics
> of the editors in question, but so are the syntactical and grammatical
> conventions, too.  Semantics, even in the hands of the honest, is a fuzzy
> beast;  the elements of exposition and structure are not. Perhaps the
> inquisitive mind is correctly labeled stupid, or irresponsible, if it
> cannot decipher some fine piece of programming crypsis.  And perhaps not.
> It can just as perhaps be that there is an equal, even greater
> irresponsibility, on the part of those who have taken up the task of
> clarifying the obscure to the confused.  There is no greater arrogance,
> and it seems to me particularly prevalent among the educators in the
> technical fields, than pretending any hermeneutic, an effective
> hermeneutic. Sadly, most of these creatures cannot tell a verb from a
> noun, and scarcely know where modifiers are best, most effectively, posted
> to qualify their objects, let alone use those same nouns and verbs and
> modifiers to explain the intricacies of a subject.  Tell one of these
> cognoscenti that language is about COMMUNICATION, and they begin pointing
> abstract fingers at their critics, and labeling.
> 
> Perhaps the reason programs are so inelegant, and so user-UNfriendly, and
> so bug-infested, is a natural consequence, when a field is dominated by
> creatures who know much more than they comprehend, and much less than they
> need to?  If, I think, you cannot explain a thing to me, you do not
> understand it.  After all, I'm a lot smarter than you, and I have
> thankfully learned make out a fool however obscurely he covers himself.

I take my hat off to you, sir or madam, that is a brilliant satire of
pretentious self-important impenetrable prose complaining about the lack of
readability of another text. Although I found that the occasional
grammatical errors (such as the missing "how to" from the last sentence),
which I assume are deliberate, were a bit heavy handed and more distracting
than ironic.

Nevertheless, a masterful job. You made me laugh.


-- 
Steven