On Aug 12, 3:32 am, Paul Boddie <p...@boddie.org.uk> wrote: > Maybe the problem is that although everyone welcomes contributions and > changes (or says that they do), the mechanisms remain largely beyond > criticism.
FWIW, I support the idea the regular docs incorporating links to freely editable wiki pages. That will at least make it easier for people to make changes or add notes. That being said, I would like to add a few thoughts about the current process. ISTM that important corrections (when the docs are clearly in error) tend to get made right away. What is more interesting are the doc requests that get rejected and why: * Many doc requests come from people just learning the language (that makes sense because the learning process involves reading the docs). Unfortunately, a fair number of those requests are flat-out wrong or represent a profound misunderstanding of the feature in question. That may be an indicator that the docs need to be improved, but the specific suggestion can be inane. * Some doc requests come from people who simply do not like the feature in question. It is natural for tastes, styles, and preferences to vary; however, we do have a firm rule that Guido's tastes, styles, and preferences are the ones that go into the language. So the doc writers need to try to channel Guido instead of fighting him. So, if you think eval() is evil (I don't but many do), we're not going to document that eval() should *never* be used. If you hate super(), that's too bad -- the docs need to describe what it does and how it was intended to be used -- the docs are no place for diatribes on why inheritance is over-used and why you think the world would be a better place without mixins or multiple inheritance. * Then, there is a matter of where to put a particular piece of documentation (how many times do you repeat a concept that pervades the language). Hashing is a good example. The docs can discuss how some objects hash to their object id and that object ids can change from run-to-run, but if someone gets tripped-up by the idea (hey, my set reprs changed between runs, wtf!), they want the docs updated in the specific place that tripped them up (i.e. you must put big red warnings in the set documentation, and the dict documentation, and everywhere else a hash gets used ...). The core problem is that the docs are interrelated -- the one place you're looking for documentation of a specific builtin or function can't contain every concept in the language. * Some behaviors are intentionally left unspecified. For the longest time, Tim did not want to guarantee sort stability. This left him free to continue to search for algorithmic improvements that did not have stability. Later, the property was deemed so important that it did become a guaranteed behavior. Also, some things are unspecified to make things easier for other implementations (IronPython, PyPy, Jython, etc.) We need to make sure that some one doesn't casually go through the docs making doc promises that are hard to keep. * Some things are just plain difficult to fully explain in English and not misrepresent that actual behavior. For example, the str.split () docs have been continuously tweaked over the years. Even now, I think there are corner cases that are not fully captured by the docs. Casual edits to str.split() docs are more likely than not to take them farther away from the truth. * Then, there is the problem of talking too much. A book could be written about super(), but that shouldn't all go into the docs for the super builtin. Beginners often want to master all the builtins and they try to read the doc page on builtin functions. It used to be that you could read through the builtin descriptions in a few minutes. Now, it takes a concerted effort to get through. It is hard to take a sip of water from a firehose. Too much information has make a function harder to understand. * My biggest pet peeve are requests to fill the docs with big red warnings. I do not want the docs to look like a mine field. The warnings should be reserved for a handful of security or data corruption risks. For the most part, the docs should be matter-of-fact, explaining what a function or method does and how it was intended to be used. Preferred: "The value str.letters is locale dependent" Not preferred: "Caution, the str.letters value can be adversely affected by the locale setting (it could even change length!); use this only when you are certain the locale setting will not violate any of your program invariants; consider using a string literal instead; I hate string.letters and think Guido was smoking crack when it was introduced." * Another category of rejected doc requests come from people looking for absolution from one of their programming bugs. It typically takes the form of, "I made an assumption that the language did X, but it did Y and my program didn't do what I wanted; therefore, the docs must be to blame and they must change ...". The suggestion is "I was suprised" implies "the docs are hosed". The fact is that people with diffferent backgrounds are going to have different expectations and someone is going to get "surprised". The docs need to say what functions do, but they don't need to be changed everytime someone writes a buggy program. In short, most doc requests that get rejected are requests that didn't actually improve the documentation. I do support links from the regular docs to an external wiki but the main docs should continue to go through the regular process using the tracker. Raymond -- http://mail.python.org/mailman/listinfo/python-list