Python docs [was: function with a state]

Discussion in 'Perl Misc' started by Xah Lee, Mar 9, 2005.

  1. Xah Lee

    Xah Lee Guest

    thanks for the help...

    -------
    the python doc is stilted. It tried to organized the thing and with a
    style around some highbrow inane "computer science" outlook.

    i found the little section on global
    (http://python.org/doc/2.4/ref/global.html)
    and can't make out what shit it is trying to say without having read
    and figured out the entire doc of its style and contexts and
    definitions. (formalization varies and computing model and jargons mean
    different things.)

    Python doc writers needs to re-organize and re-style their docs so that
    its organization is towards programing, as opposed to how the
    implementation works (as in the Lib Reference), or a formalization of
    the language spec. (e.g. the fucking semi-joke of "(for language
    lawyers)" and BNF and those Runtime "Service" shits.) Its style
    needs to shift from highbrowism to pragmatic and exemplary.

    I've addressed some of the jargon-riding ills common in industry with
    examples from the Python doc, archived here:
    http://xahlee.org/Periodic_dosage_dir/t2/xlali_skami_cukta.html

    as to the way of its stiltedenss and academicism, which make it hard
    for programers to find or apply any info, i'll expound later.

    PS just so that there is no misunderstanding: The docs of unix and
    Perl, are fucking criminally incompetent. Python docs, although stilted
    in a academic way, but nevertheless is solid, and its writers are
    educated, and tried best to make it a quality one, albeit sometimes
    inevitably showed some masterbation and jargonization. While the unix
    and Perl docs, (and essentially all things out of unix, e.g. Apache
    docs), are fucking incompetent drivels and in many cases exorbitant
    lies, and they semi-present it as humor and want and brainwash people
    to take them as norm. In a nutshell, these people are spreading
    untruths and indirectly are causing massive harm in the computing
    industry. People, we need to stop it. This each of us can do by not
    accepting their attitudes or behavior. In online forums, work place,
    conventions, conversations etc., raise questions or otherwise voice
    your opinion whenever you can.

    Xah

    http://xahlee.org/PageTwo_dir/more.html
    Xah Lee, Mar 9, 2005
    #1
    1. Advertising

  2. Xah Lee

    Xah Lee Guest

    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 mighthave
    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 usagefor
    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

    ∑ http://xahlee.org/PageTwo_dir/more.html
    Xah Lee, Mar 24, 2005
    #2
    1. Advertising

  3. Xah Lee

    John Bokma Guest

    John Bokma, Mar 24, 2005
    #3
  4. Xah Lee

    Xah Lee Guest

    there is a Python, pithy
    mighty, lissome, and tabby
    algorithms it puffs
    tim-toady it engulfs
    and sways universality


    there is a camel, lanky
    ugly, petty, ungainly
    foolhardy comports
    hacking it supports
    and toadies eunuch's fancy

    Xah

    ∑ http://xahlee.org/PageTwo_dir/more.html

    Michael Spencer wrote:
    > Or if not a doc patch, how about a limerick?
    >
    > Michael
    Xah Lee, Mar 25, 2005
    #4
  5. Xah Lee

    Guest

    In comp.lang.perl.misc Xah Lee <> wrote:
    > The Python doc is relatively lousy, from content organization to the
    > tech writing quality.


    Which has precisely what to do with most of the groups to which you
    cross-posted?

    > Problem: They all have the same priority (which is higher than that of
    > the Boolean operations).


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


    The meaning is perfectly plain. By the way did you perhaps mean
    'confusing' or 'confused'? I normally regard language flames
    otiose but here, since you are trying to correct other people's
    writing, fair game.

    > And, from pure writing aspect, the sentence ?...(which is ...)? is
    > some kind of a juvenile latch on. If the author intent to make that


    Do you mean... 'if the author's intent is to make' or 'if the author
    intends to'?

    > 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


    Should that not be 'parentheses are likely to be used'?

    It is not rare at all. Besides, little asides like this are an ideal
    way to reinforce thoughts about operator preference and more helpful
    then memorising a table.

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


    I suggest you look up the meaning of the word.

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


    You mean 'are evaluated'. Your rephrasing is also incomplete since
    it doesn't note that z will not be evaulated if x < y is false.

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


    Really? In a reference manual such matters should be fully specified
    regardless of what happens in other languages.

    > Problem: <> and != are alternate spellings for the same operator. != is
    > the preferred spelling; <> is obsolescent


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


    Really? Actually it is very important to mention it in the correct
    place in a reference manual. Do you understand the concept of
    maintaining old code?

    > I'm in fact somewhat surprised by this poor quality in writing. The


    Really? The writing in the manual seems simple, straight-forward and
    clear to me (knowing no Python). Unlike your writing.

    > more egregious error is the hardware-oriented organization aka
    > technical drivel.


    What on earth does this mean?

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


    I think that this is an excellent description of your own writing.

    Axel
    , Mar 25, 2005
    #5
  6. Xah Lee

    Xah Lee Guest

    [perl-python] limericks

    Better:

    there is a Python, pithy
    mighty, lissome, and tabby
    algorithms it puffs
    conundrums it snuffs
    and cherished by those savvy


    there is a camel, kooky
    ugly, petty, ungainly
    hacking it supports
    TIMTOWTDI it sports
    and transports DWIM-wit's fancy

    Xah

    ∑ http://xahlee.org/PageTwo_dir/more.html
    Xah Lee, Mar 25, 2005
    #6
  7. wrote:
    >>The Python doc, though relatively incompetent, but the author have


    Really, how could those morons even dream of creating a language,
    and even writing docs to accompany it??

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


    Well, man-pages are at least coherent and precise.
    It's not literature, it's technical documentation!

    >
    > I think that this is an excellent description of your own writing.


    :)

    To be sure, he's a stupid troll, but I think you shouldn't insult
    him for being bad at English. I bet you (or most Western people
    anyway) have trouble getting fluent in an Asian language. Imagine
    the lingua franca were Chinese, non English...
    Ulrich Hobelmann, Mar 25, 2005
    #7
  8. Please stop cross-posting this stuff!

    --
    Keith Thompson (The_Other_Keith) <http://www.ghoti.net/~kst>
    San Diego Supercomputer Center <*> <http://users.sdsc.edu/~kst>
    We must do something. This is something. Therefore, we must do this.
    Keith Thompson, Mar 25, 2005
    #8
  9. Re: [perl-python] limericks

    Xah Lee wrote:
    > Better:
    >
    > there is a Python, pithy
    > mighty, lissome, and tabby
    > algorithms it puffs
    > conundrums it snuffs
    > and cherished by those savvy
    >
    >
    > there is a camel, kooky
    > ugly, petty, ungainly
    > hacking it supports
    > TIMTOWTDI it sports
    > and transports DWIM-wit's fancy
    >
    > Xah
    >
    > ∑ http://xahlee.org/PageTwo_dir/more.html
    >


    These "limericks" just don't work, do they? I mean, the number of
    syllables is just way off, and then the rhymes are just plain wrong. By
    all means, don't stop trying, but don't quit your day job yet.
    Andras Malatinszky, Mar 26, 2005
    #9
  10. Xah Lee

    Roy Smith Guest

    Re: [perl-python] limericks

    In article <_w41e.74579$SF.14703@lakeread08>,
    Andras Malatinszky <> wrote:

    > Xah Lee wrote:
    > > Better:
    > >
    > > there is a Python, pithy
    > > mighty, lissome, and tabby
    > > algorithms it puffs
    > > conundrums it snuffs
    > > and cherished by those savvy
    > >
    > >
    > > there is a camel, kooky
    > > ugly, petty, ungainly
    > > hacking it supports
    > > TIMTOWTDI it sports
    > > and transports DWIM-wit's fancy
    > >
    > > Xah
    > >
    > > ∑ http://xahlee.org/PageTwo_dir/more.html
    > >

    >
    > These "limericks" just don't work, do they? I mean, the number of
    > syllables is just way off, and then the rhymes are just plain wrong. By
    > all means, don't stop trying, but don't quit your day job yet.


    A poetry critic, Andras
    In a huff at the tempo, alas!
    The meter's too free,
    So he's telling Xah Lee,
    Nocturnal employment won't last!
    Roy Smith, Mar 26, 2005
    #10
  11. Xah Lee

    Xah Lee Guest

    Python doc “3.6.4 Mutable Sequence Types†at
    http://python.org/doc/2.4/lib/typesseq-mutable.html

    in which contains the documentation of the “sort†method ofa list.
    Quote:

    --------------
    ..sort([cmp[, key[, reverse]]])
    sort the items of s in place
    (7), (8), (9), (10)

    ....

    (8)

    The sort() method takes optional arguments for controlling the
    comparisons.

    cmp specifies a custom comparison function of two arguments (list
    items) which should return a negative, zero or positive number
    depending on whether the first argument is considered smaller than,
    equal to, or larger than the second argument: "cmp=lambda x,y:
    cmp(x.lower(), y.lower())"

    key specifies a function of one argument that is used to extract a
    comparison key from each list element: "cmp=str.lower"

    reverse is a boolean value. If set to True, then the list elements
    are sorted as if each comparison were reversed.

    In general, the key and reverse conversion processes are much faster
    than specifying an equivalent cmp function. This is because cmp is
    called multiple times for each list element while key and reverse
    touch each element only once.

    Changed in version 2.3: Support for None as an equivalent to omitting
    cmp was added.

    Changed in version 2.4: Support for key and reverse was added.

    ------------------

    As a piece of documentation, this is a relatively lousy one.

    The question Python doc writers need to ask when evaluating this piece
    of doc are these:

    * can a experienced programer (expert at several languages) who is new
    to Python, and also have read the official Python tutorial, can he,
    read this doc about â€sortâ€, and know exactly how to use it with all
    the options?

    * can this piece of documentation be rewritten fairly easily, so that
    the answer to the previous question is a resounding yes?

    To me, the answers to the above questions are No and Yes. Here are some
    issues with the doc:

    * in the paragraph about “Keyâ€, the illustration given is:
    “cmp=str.lowerâ€. Shouldn't it be “key=str.lowerâ€?

    * This doc lacks examples. One or two examples will help a lot,
    especially to less experienced programers. (which comprises the
    majority of readers) In particular, it should give a full example of
    using the cmp predicate and one with key.

    * This doc fails to address what happens when the predicate and the
    short cut version conflicts. e.g.
    myList.sort(lambda x,y: cmp(x[0], y[0]), lambda x: str(x[0]), False )

    * on the whole, the way this doc is written does not give a clear
    picture of what exactly is happening (think of mathematics) with sort,
    nor the roles of the supplied options, nor how to use them.

    Quick remedy: add a examples of using cmp predicate. And a example
    using “key†predicate. Add example of Using one of them andwith
    reverse. (the examples need not to come with much explanations. One
    sentence annotation will do. )

    Other than that, the way the doc is layed out with a terse table and
    run-on footnotes (as appeared in other pages) is not inductive. For a
    better improvement, there needs to be overhaul of the organization and
    the attitude of the entire doc. The organization needs to be programing
    based, as opposed to implementation or computer science based. (in this
    regard, one can learn from the Perl folks). As to attitude, the writing
    needs to be Python-as-is, as opposed to computer science framework.
    I'll might have to give more details in the future, but I've made some
    headway in this respect before; peruse:

    http://xahlee.org/Periodic_dosage_dir/t2/xlali_skami_cukta.html

    Xah

    ∑ http://xahlee.org/PageTwo_dir/more.html

    ☄
    Xah Lee, Mar 28, 2005
    #11
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Xah Lee
    Replies:
    6
    Views:
    312
    Xah Lee
    Mar 28, 2005
  2. KYG
    Replies:
    2
    Views:
    886
    Ian Collins
    Aug 18, 2008
  3. Brandon Craig Rhodes

    python docs redirect on python.org is old

    Brandon Craig Rhodes, Apr 5, 2009, in forum: Python
    Replies:
    2
    Views:
    265
    barisa
    Apr 5, 2009
  4. Stéphane Wirtel
    Replies:
    0
    Views:
    184
    Stéphane Wirtel
    Apr 19, 2007
  5. Al
    Replies:
    1
    Views:
    152
    Henry Law
    Oct 16, 2005
Loading...

Share This Page