The Python doc is relatively lousy, from content organization to the tech writing quality.
I think i'll just post snippets of my comments as i find them. (and feel like exposing) Python doc: http://python.org/doc/2.4/lib/comparisons.html Quote: Comparison operations are supported by all objects. They all have the same priority (which is higher than that of the Boolean operations). Comparisons can be chained arbitrarily; for example, x < y <= z is equivalent to x < y and y <= z, except that y is evaluated only once (but in both cases z is not evaluated at all when x < y is found to be false). -- Problem: âComparison operations are supported by all objects.â This is very vague and ambiguous. The word âobjectâ has generic English meaning as well might have very technical meaning in a language. In Python, it does not have very pronounced technical meaning. For example, there's a chapter in Python Library Ref titled â2. Built-In Objectsâ, and under it a section â2.1 Built-in Functionsâ. Apparently, functions can't possibly be meant as a âobjectâ for comparisons. Now suppose we take the object in the sentence to be sensible items as numbers, lists etc. The clause âsupported by all objectsâ is ambiguous. What is meant by âsupportedâ? -- Problem: They all have the same priority (which is higher than that of the Boolean operations). This sentence is very stupid, in multitude of aspects. The âpriorityâ referred to here means operator precedence. It tries to say that the comparison operator has higher syntactical connectivity than boolean operators. E.g. âFalse and False==Falseâ means âFalse and (False==False)â and not â(False and False)==Falseâ. However, the âtheyâ pronoun from the context of previous sentence, refers to âthe comparison operationâ, not âoperatorâ. So, it conjures the reader to think about some âoperation precedenceâ, which in itself cannot be ruled out as nonsense depending on the context. Very fucking stupid confusional writing. And, from pure writing aspect, the sentence â...(which is ...)â is some kind of a juvenile latch on. If the author intent to make that point, say it in its own sentence. e.g. The comparison operators have higher precedence than boolean operators. It would be better to not mention this at all. For practical considerations, very rare is the case of mixing boolean and comparison operators, and if so, parenthesis are likely used and is indeed a good practice. The proper place for operator precedence is a table list all such, giving a clear view, and in some appendix of language spec. -- Problem: Comparisons can be chained arbitrarily; for example, x < y <= z is equivalent to x < y and y <= z, except that y is evaluated only once (but in both cases z is not evaluated at all when x < y is found to be false). Drop the word âarbitrarilyâ. It has no meaning here. the whole sentence is one fucked up verbiage of pell-mell thinking and writing. Here's one example of better: Comparisons can be chained, and is evaluated from left to right. For example, x < y <= z is equivalent to (x < y) <= z. With respect to documentation style, it is questionable that this aspect needs to be mentioned at all. In practice, if programers need to chain comparisons, they will readily do so. This is not out of ordinary in imperative languages, and evaluation from left to right is also not extraordinary to cost a mention. -- Problem: <> and != are alternate spellings for the same operator. != is the preferred spelling; <> is obsolescent Very bad choice of term âspellingsâ -- not a standard usage for computer language operators. Better: â!=â can also be written as â<>â. If â<>â is not likely to go out in future versions, don't even mention about âpreferenceâ, because it has no effective meaning. (if one wants to wax philosophical about âprograming estheticsâ, go nag it outside of language documentation.) In general, when something is obsolete or might go defunct in the future, consider not even mentioning that construct. If necessary, add it in a obscure place, and not adjacent to critical info. In many places of Python documentation, this is breached. -- This is just a quick partial analysis of one episode of incompetence i see in Python docs in the past months i've had the pleasure to scan here and there. A extreme pain in the ass. I'm in fact somewhat surprised by this poor quality in writing. The more egregious error is the hardware-oriented organization aka technical drivel. But that i accept as common in imperative language communities and in general the computing industry. But the poor quality in the effectiveness and clarity of the writing itself surprised me. As exhibited above, the writing is typical of programers, filled with latch on sentences and unclear thinking. (they in general don't have a clear picture of what they are talking about, and in cases they do, they don't have the writing skills to express it effectively. (just as a footnote: this writing problem isn't entirely the fault of programers or Python doc writers. In part the English language (or in general natural languages) are to blame, because they are exceptionally illogical and really take years to master as a art by itself.)) The Python doc, though relatively incompetent, but the author have tried the best. This is in contrast to documentations in unix related things (unix tools, perl, apache, and so on etc), where the writers have absolutely no sense of clear writing, and in most cases don't give a damn and delight in drivel thinking of it as literary. A criminal of this sort that does society huge damage is Larry Wall and the likes of his cohorts in the unix community. (disclaimer: this is a piece of opinion.) addendum: quality writing takes time. Though, the critical part lies not in the mastery of writing itself, but in clarity of thinking of what exactly one wants to say. So, next time you are writing a tech doc, first try to have a precise understanding of the object, and then know exactly what is that you want to say about it, then the writing will come out vastly better. If the precise understanding of the object is not readily at hand (which is common and does not indicate incompetence), being aware of it helps greatly in its exposition. This and past critics on Python documentation and IT doc in general is archived at http://xahlee.org/Periodic_dosage_dir/t2/xlali_skami_cukta.html Xah [EMAIL PROTECTED] â http://xahlee.org/PageTwo_dir/more.html -- http://mail.python.org/mailman/listinfo/python-list