Re: Social problems of Python doc [was Re: Python docs disappointing]
On 18 Aug, 05:19, ru...@yahoo.com wrote: Yes, I agree. I should have mentioned this as an exception in my wikis suck diatribe. Although it far better than most wiki's I've seen, it is still pretty easy to find signs of typical wiki-ness. On the Documentation page my first click was on AnnotableDocumentation: 404. Well, Annotatable Documentation is an external link. All we can do in such cases is to tidy such stuff up, mark it as invalid, or remove it. Second try, DoumentationDiscussion: two very short paragraphs dated 2003. Right. There are parts of the Wiki which were used actively in the past but which have fallen into disrepair. Some pages lack focus - they've been created according to old school Wiki conventions which I regard as being somewhat obsolete (just creating new pages all over the place to cover whatever happens to be in the writer's head at the time) - and every now and again, I attempt to rationalise these pages and focus their content. After that I found some useful (in general though not what I was looking for) information but not a good first impression. (Well not exactly first, in fairness I have used other wiki sections such as the Templating page and found them very useful.) It needs work, of course. [...] I took a look at the PHP docs last night which seem pretty well done. The User Comments looked rather as I expected, there was useful info but most did not contain documentation quality writing. So if they are used as a source for improving the docs, there clearly must be a pretty large amount of editorial effort required, although much of it is probably just filtering out comments that don't provide any information appropriate for inclusion in the docs. They list 38 names under User Note Maintainers (http://www.php.net/manual/en/preface.php) Unfortunately I couldn't find a description of what these people actually do. I don't know how much work was involved in removing the comments that are no longer there. Indeed. There's always the editorial bottleneck unless it's a total free-for-all situation. I've remarked before about how user comments don't necessarily add significantly to documentation, which is an assertion that some people make, and there definitely does need to be a process of integrating the best feedback into the main work. The crucial difference between a Wiki and an annotation system is the combination of the contribution and editorial aspects in a Wiki - you edit the actual work, and people can decide whether it's a good edit or not - in contrast to their separation in most annotation systems. In some cases, strict annotation systems are probably better: the GPLv3 annotation system was oriented towards discussion of the text, and that's not so effectively done in a Wiki. Again, I don't mean to sound like I am dissing the idea of annotatable docs -- I think it is a good idea and will provide useful supplementary information. Where there's a separation of annotation and editing, I worry about the editorial bottleneck. I also worry about handprint edits more generally, where people just want to leave their touch on the work without actually contributing anything of substance. But I continue to question whether this will result in improvements in the docs themselves (which is my main interest) unless: 1. The purpose of the wiki is clearly marketed as soliciting suggestions, rewrites, etc destined ultimately for inclusion in the docs. I'm happy to see tangential work rather than stuff which fills exactly the same role as the current documentation. For example, the Python module of the week articles (PyMOTW, [1]) are exactly the kind of tangential work that could be encouraged, even though that is not so much a collaborative work itself. Paul [1] http://www.doughellmann.com/PyMOTW/ -- http://mail.python.org/mailman/listinfo/python-list
Re: Social problems of Python doc [was Re: Python docs disappointing]
ru...@yahoo.com writes: I took a look at the PHP docs last night which seem pretty well done. The User Comments looked rather as I expected, there was useful info but most did not contain documentation quality writing. So if they are used as a source for improving the docs, there clearly must be a pretty large amount of editorial effort required, although much of it is probably just filtering out comments that don't provide any information appropriate for inclusion in the docs. The comments section contains questions from users and answers to those questions from other users. What you may be missing is the part of the comments useful to the doc maintainers is primarily the user questions, rather than the user answers. The questions show the doc writer exactly what parts of the official doc are unclear or incomplete. The user-written answers may be wrong or generally crap, but the doc writer now knows what to do to improve the doc. That's why it's such a win to have the comments on the same page as the official docs. See also the user-commented http://book.realworldhaskell.org/read/ where the comments really helped clarify the finished (dead tree) text. -- http://mail.python.org/mailman/listinfo/python-list
Re: Social problems of Python doc [was Re: Python docs disappointing]
On Aug 12, 12:15 pm, Raymond Hettinger pyt...@rcn.com wrote: [Xah Lee] i've wrote several articles about this issue, total time spend on this is probably more than 2 months full-time work. See: • Python Documentation Problems http://xahlee.org/perl-python/python_doc_index.html I just read you post. You did devote a substantial amount of time to the project. Some of your criticisms are valid. Wish you had posted patches, I think many of them would have been accepted. Since you wrote this a few years ago, many examples have been added to the docs and more are forthcoming. I often receive thank you emails for 2 particular articles, which are most frequently google searched as indicated by my weblog: • Python Doc Problem Example: gzip http://xahlee.org/perl-python/python_doc_gzip.html • Python Doc Problem Example: sort() http://xahlee.org/perl-python/python_doc_sort.html • Sorting in Python and Perl http://xahlee.org/perl-python/sort_list.html Some are the criticisms are valid; others seem off-base. Here are a few thoughts on list.sort() for those who are interested: * The key= and reversed= parameters are not intended for special cases, leaving cmp= for the general case. They were intended to be full replacements. In Python3.x, the cmp function is gone. * The interaction of the key= and cmp= functions can be made to interact (the key function is first applied to every element and the cmp function then gets applied to the results of the key function). This isn't a normal or intended use case, so the docs don't delve into the subject. * The reversed parameter does more than list.sort() followed by list.reverse(). It also preserves stability in the event of equal keys: sorted([(1,2), (1,3)], key=itemgetter(0), reverse=True) [(1,2), (1,3)] So it was not correct to say that the following are equivalent: li.sort(lambda x, y: cmp(x[1],y[1]), reverse=True) li.sort(lambda x, y: cmp(y[1],x[1])) * We should link the sorted() and list.sort() docs to the sorting how-to (with a fuller discussion on the art of sorting including a discussion of operator.itemgetter() and operator.attrgetter() which were designed to work with the key= parameter. Here are a few thoughts on list.sort() for those who are interested: After one more reading of Xah Lee's posts on the documentation for sort, here are couple more thoughts: * The reason that list.sort() allows None for the cmp parameter is not so that you can write list.sort(None). It was put there to make it easier for people writing function definitions where the cmp function is a possible argument: def sort_and_chop(seq, maxlen, cmp=None): s = seq[:] s.sort(cmp) # needs to accept None as a possible argument return s[:maxlen] * The reason for implementing the key= parameter had nothing to do with limitations of Python's compiler. Instead, it was inspired by the decorate-sort-undecorate pattern. Hi Raymond, thanks for the many points. They are informative, some i disagree, but it's getting into detail. I don't know python 3.0, will have to look into its sort in the future. This part i don't particular agree: * The reason for implementing the key= parameter had nothing to do with limitations of Python's compiler. Instead, it was inspired by the decorate-sort-undecorate pattern. The decorate-sort-undecorate pattern is a compiler limitation, for most of today's langs. I'm not sure, but i think some of the fancy functional langs automatically detect such and optimize it away, to various degrees. ... my criticism is usually written in a style catered to irritate a particular class of coder i call tech geekers (they think of themselfs with their idiotic term “hackers”). So, parts are exaggerated. It'd be more clear to say, that the reason for python's “key”, and as a “solution” or need of the decorate-sort-undecorate issue, can be attributed to the current state of the art of popular imperative language's compilers (induced by such lang's semantics). again, i haven't studied python 3.0 to see what it has changed with sort, and thanks for the informative post. I find it intriguing that it doesn't have “cmp” anymore as you say maybe when i actually study it and i'll come away with rage and rants. LOL. Xah ∑ http://xahlee.org/ ☄ -- http://mail.python.org/mailman/listinfo/python-list
Re: Social problems of Python doc [was Re: Python docs disappointing]
Xah Lee wrote: On Aug 12, 12:15 pm, Raymond Hettinger pyt...@rcn.com wrote: * The reason for implementing the key= parameter had nothing to do with limitations of Python's compiler. Instead, it was inspired by the decorate-sort-undecorate pattern. The decorate-sort-undecorate pattern is a compiler limitation, for most of today's langs. I'm not sure, but i think some of the fancy functional langs automatically detect such and optimize it away, to various degrees. You mean people use that pattern as a fast alternative in languages where user-defined functions are very slow, like Python and Mathematica? -- Dr Jon D Harrop, Flying Frog Consultancy Ltd. http://www.ffconsultancy.com/?u -- http://mail.python.org/mailman/listinfo/python-list
Re: Social problems of Python doc [was Re: Python docs disappointing]
Jon Harrop j...@ffconsultancy.com wrote: Xah Lee wrote: [...] Please do not feed this well-known troll. He is known to spew some remotely on-topic junk into a bunch of unrelated NGs and to enjoy the ensuing confusion. jue -- http://mail.python.org/mailman/listinfo/python-list
Re: Social problems of Python doc [was Re: Python docs disappointing]
Jon Harrop j...@ffconsultancy.com writes: You mean people use that pattern as a fast alternative in languages where user-defined functions are very slow, like Python and Mathematica? It really doesn't matter whether the language is fast or slow--there are going to be applications where calling the comparison function multiple times per element is slower than calling it once per element and storing the result. Note the Haskell idiom (sortBy (compare`on`f) xs) is similar to DSU but calls the comparison function multiple times. Python 3.0 went overboard by actually removing the cmp argument and requiring use of the key argument. That requires various kludges if the key is, say, a tree structure that has to be recursively compared with another such structure. Maybe then can bring back cmp someday. -- http://mail.python.org/mailman/listinfo/python-list
Re: Social problems of Python doc [was Re: Python docs disappointing]
Jon Harrop wrote: Xah Lee wrote: On Aug 12, 12:15 pm, Raymond Hettinger pyt...@rcn.com wrote: * The reason for implementing the key= parameter had nothing to do with limitations of Python's compiler. Instead, it was inspired by the decorate-sort-undecorate pattern. The decorate-sort-undecorate pattern is a compiler limitation, for most of today's langs. I'm not sure, but i think some of the fancy functional langs automatically detect such and optimize it away, to various degrees. You mean people use that pattern as a fast alternative in languages where user-defined functions are very slow, like Python and Mathematica? Do not give this Xah Lee idiot any attention. This asshole posts only self-serving nonsense, because he thinks it makes him sound important (when in reality, he is absolutely clueless). This idiot always cross posts to 5 or more different groups that have nothing to do with his attempts to impress people (which always fail). He's incredibly arrogant, yet incredibly clueless. -- http://mail.python.org/mailman/listinfo/python-list
Re: Social problems of Python doc [was Re: Python docs disappointing]
[Xah Lee] This part i don't particular agree: * The reason for implementing the key= parameter had nothing to do with limitations of Python's compiler. Instead, it was inspired by the decorate-sort-undecorate pattern. The decorate-sort-undecorate pattern is a compiler limitation, for most of today's langs. I'm not sure, but i think some of the fancy functional langs automatically detect such and optimize it away, to various degrees. ... my criticism is usually written in a style catered to irritate a particular class of coder i call tech geekers (they think of themselfs with their idiotic term “hackers”). So, parts are exaggerated. It'd be more clear to say, that the reason for python's “key”, and as a “solution” or need of the decorate-sort-undecorate issue, can be attributed to the current state of the art of popular imperative language's compilers (induced by such lang's semantics). I'm not following you here. If you're saying that it is possible for a compiler to automatically transform a cmp argument into a key argument, transforming O(n log n) calls into O(n) calls, then I don't see how that could be done (a cmp argument can be a C function that is not introspectable or an arbitrarily complex python function that may be difficult to analyze and transform programmatically). The key function was introduced as a simpler way for programmers to write the commonly used decorate-sort-undecorate pattern -- compiler limitations had nothing to do with it. In general, key functions are not a terribly new or inflexible concept. The SORT BY clauses in SQL are an example. That being said, it is a fair criticism of Python's compiler that it does not do much in the way of optimizations. It does a handful of basic peephole optimizations but that is about it. Other languages like Haskell fair better in this regard. Raymond -- http://mail.python.org/mailman/listinfo/python-list
Re: Social problems of Python doc [was Re: Python docs disappointing]
On 08/13/2009 08:46 AM, Paul Boddie wrote: On 13 Aug, 16:05, ru...@yahoo.com wrote: All the above not withstanding, I too think a wiki is worth trying. But without doing a lot more than just setting up a wiki, I sadly believe even a python.org supported wiki is doomed to failure. The ones on python.org seem to function reasonably well. I accept that they could be more aggressively edited, but this isn't done because there's a compromise between letting people contribute and keeping things moderately coherent, with the former being favoured. For other purposes, it would be quite acceptable to favour editorial control. Yes, I agree. I should have mentioned this as an exception in my wikis suck diatribe. Although it far better than most wiki's I've seen, it is still pretty easy to find signs of typical wiki-ness. On the Documentation page my first click was on AnnotableDocumentation: 404. Second try, DoumentationDiscussion: two very short paragraphs dated 2003. After that I found some useful (in general though not what I was looking for) information but not a good first impression. (Well not exactly first, in fairness I have used other wiki sections such as the Templating page and found them very useful.) I won't argue that providing infrastructure solves a problem - that's precisely the kind of thing I was criticising when I noted that some people will readily criticise the choice of tools to do a job instead of focusing on the job that has to be done - and you need people who are reasonably competent editors, but Wiki solutions remove a lot of technical barriers. I'm not arguing for the flavour of Wiki which implies unfettered, anonymous access from everyone on the Internet, either: the kind of Wiki that detractors portray all Wiki solutions as being in order to further their super-special it has to fit like a glove or it's totally unusable software agenda. It's quite possible to have people with somewhat more privileges than others in order to keep the peace, and they don't all need to have an entrenched editorial interest: on the current python.org Wiki sites, most of the administrators don't have an active interest in most of the content, but they are able to exercise control when it's clear that some contributors aren't particularly interested in actually improving the content. As well as having an active community effort around the existing python.org Wiki sites, there are also people who are interested in improving these offerings. What worries me is that despite such activity and such interest, many people will continue to lament the lack of vitality (or whatever other metric) of the general python.org offering, whilst retaining a blind spot for the obvious contribution that the Wikis can make to such improvement efforts. I encourage people to use wiki.python.org a lot more, should they be looking to improve the wealth of information provided by the community. Again, I agree with all of that. But my main interest is in improving the standard docs that are distributed with Python and I question a wiki's role in that. I took a look at the PHP docs last night which seem pretty well done. The User Comments looked rather as I expected, there was useful info but most did not contain documentation quality writing. So if they are used as a source for improving the docs, there clearly must be a pretty large amount of editorial effort required, although much of it is probably just filtering out comments that don't provide any information appropriate for inclusion in the docs. They list 38 names under User Note Maintainers (http://www.php.net/manual/en/preface.php) Unfortunately I couldn't find a description of what these people actually do. I don't know how much work was involved in removing the comments that are no longer there. Again, I don't mean to sound like I am dissing the idea of annotatable docs -- I think it is a good idea and will provide useful supplementary information. But I continue to question whether this will result in improvements in the docs themselves (which is my main interest) unless: 1. The purpose of the wiki is clearly marketed as soliciting suggestions, rewrites, etc destined ultimately for inclusion in the docs. 2. There is a dedicated core of doc-competent volunteers focused on extracting, condensing and editing the user comments and getting them into the docs, either directly (if the volunteers are committers -- unlikely) or through the existing tracker system. And this still fails to address the problems with the docs that aren't amenable to fixing via the tracker system. At least two of those problems are: 1. Difficultly in making large organizational changes. 2. Prevalent opinion among doc approvers that the current excessively terse style is desirerable. -- http://mail.python.org/mailman/listinfo/python-list
Re: Social problems of Python doc [was Re: Python docs disappointing]
Nathan Keel wrote: idiot ... asshole absolutely clueless ... idiot ...incredibly arrogant, yet incredibly clueless. To me, such name-calling is as obnoxious as the intended target. tjr -- http://mail.python.org/mailman/listinfo/python-list
Re: Social problems of Python doc [was Re: Python docs disappointing]
On Mon, 17 Aug 2009 13:56:13 -0700, Paul Rubin wrote: Python 3.0 went overboard by actually removing the cmp argument and requiring use of the key argument. That requires various kludges if the key is, say, a tree structure that has to be recursively compared with another such structure. Maybe then can bring back cmp someday. I'm having trouble understanding this, which may be my weakness rather than yours, but could you give an actual (simplified?) example I can run, where cmp would work but key wouldn't? -- Steven -- http://mail.python.org/mailman/listinfo/python-list
Re: Social problems of Python doc [was Re: Python docs disappointing]
Thanks Raymond. I've been out of python community for a couple of years. I've saved your messages and will study it later when next time i work in python. Possibly today and will reply in some of your points. But just wanted to say thanks for improving python. Also, sometimes ago out of the blue i noticed someone has posted a bug on python's gzip doc with acknowledgement. http://bugs.python.org/issue2406 Thank you M.-A. DARCHE (madarche). Also, i noticed python doc now and later has improved a lot since last i looked around python 2.4. For one thing, the html/xhtml is now valid html. Good riddence of the fucking TeX. Also, code examples have syntax coloring on. Xah ∑ http://xahlee.org/ ☄ On Aug 12, 12:15 pm, Raymond Hettinger pyt...@rcn.com wrote: [Xah Lee] i've wrote several articles about this issue, total time spend on this is probably more than 2 months full-time work. See: • Python Documentation Problems http://xahlee.org/perl-python/python_doc_index.html I just read you post. You did devote a substantial amount of time to the project. Some of your criticisms are valid. Wish you had posted patches, I think many of them would have been accepted. Since you wrote this a few years ago, many examples have been added to the docs and more are forthcoming. I often receive thank you emails for 2 particular articles, which are most frequently google searched as indicated by my weblog: • Python Doc Problem Example: gzip http://xahlee.org/perl-python/python_doc_gzip.html • Python Doc Problem Example: sort() http://xahlee.org/perl-python/python_doc_sort.html • Sorting in Python and Perl http://xahlee.org/perl-python/sort_list.html Some are the criticisms are valid; others seem off-base. Here are a few thoughts on list.sort() for those who are interested: * The key= and reversed= parameters are not intended for special cases, leaving cmp= for the general case. They were intended to be full replacements. In Python3.x, the cmp function is gone. * The interaction of the key= and cmp= functions can be made to interact (the key function is first applied to every element and the cmp function then gets applied to the results of the key function). This isn't a normal or intended use case, so the docs don't delve into the subject. * The reversed parameter does more than list.sort() followed by list.reverse(). It also preserves stability in the event of equal keys: sorted([(1,2), (1,3)], key=itemgetter(0), reverse=True) [(1,2), (1,3)] So it was not correct to say that the following are equivalent: li.sort(lambda x, y: cmp(x[1],y[1]), reverse=True) li.sort(lambda x, y: cmp(y[1],x[1])) * We should link the sorted() and list.sort() docs to the sorting how-to (with a fuller discussion on the art of sorting including a discussion of operator.itemgetter() and operator.attrgetter() which were designed to work with the key= parameter. Raymond -- http://mail.python.org/mailman/listinfo/python-list
Re: Social problems of Python doc [was Re: Python docs disappointing]
On 08/12/2009 12:27 PM, Raymond Hettinger wrote: On Aug 12, 3:32 am, Paul Boddiep...@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: [...snip interesting categorization of bad doc enhancement suggestions...] 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. What is the purpose of such a wiki? 1. To provide hopefully useful adjunct information for each doc page? 2. To provide a source of input for improving the next version of the docs? In general I have a low opinion of wikis. Nearly all the ones I've seen are trash heaps of out-dated and wrong information, atrocious writing, and comments that look like the middle of some arcane usenet thread. They lack organization making it very difficult to find the needles of good information in the haystack of junk. The only one that seems to work is Wikipedia and it works because it has a very heavy-weight process controlling contributions. (And even then, my biggest complaint with Wikipedia is the poor writing quality in a lot of articles.) I'm not trying to be negative, only pointing out that to serve either of the goals I asked about above, a wiki will probably require a considerable management effort that should be faced up front. To simply set up a wiki and wait for it to self-organize (as I here read once) is a pipe-dream. How will it be managed? Anything written stays? If not what standards are used to remove junk entries? Wrong entries? Questionable entries? Who will do this? Will they act based on their own judgment or some documented formal standards? What happens to comments when a new doc version is released? What happens when entries become obsolete? What happens when comments are disputed? If the goal is (2) what kind of wiki contributions are being solicited (I don't understand what this sentence means? a complete rewrite of a section?) and how is that communicated? Who will take a long string of wiki comments constituting a discussion and condense them into something that can be submitted as a doc patch? (This I suspect is where the work is, where someone with good writing skills is needed.) Will this process be sufficient to raise the quality of the docs significantly, or are other steps also needed such as an attitude shift in what the core committers consider acceptable? If the goal is (1) above, it could potentially have a deleterious effect on the docs in that it will be easier to respond to requests to expand some description with, there's no need since that is covered in (or belongs in) the wiki comments. All the above not withstanding, I too think a wiki is worth trying. But without doing a lot more than just setting up a wiki, I sadly believe even a python.org supported wiki is doomed to failure. -- http://mail.python.org/mailman/listinfo/python-list
Re: Social problems of Python doc [was Re: Python docs disappointing]
On 13 Aug, 16:05, ru...@yahoo.com wrote: All the above not withstanding, I too think a wiki is worth trying. But without doing a lot more than just setting up a wiki, I sadly believe even a python.org supported wiki is doomed to failure. The ones on python.org seem to function reasonably well. I accept that they could be more aggressively edited, but this isn't done because there's a compromise between letting people contribute and keeping things moderately coherent, with the former being favoured. For other purposes, it would be quite acceptable to favour editorial control. I won't argue that providing infrastructure solves a problem - that's precisely the kind of thing I was criticising when I noted that some people will readily criticise the choice of tools to do a job instead of focusing on the job that has to be done - and you need people who are reasonably competent editors, but Wiki solutions remove a lot of technical barriers. I'm not arguing for the flavour of Wiki which implies unfettered, anonymous access from everyone on the Internet, either: the kind of Wiki that detractors portray all Wiki solutions as being in order to further their super-special it has to fit like a glove or it's totally unusable software agenda. It's quite possible to have people with somewhat more privileges than others in order to keep the peace, and they don't all need to have an entrenched editorial interest: on the current python.org Wiki sites, most of the administrators don't have an active interest in most of the content, but they are able to exercise control when it's clear that some contributors aren't particularly interested in actually improving the content. As well as having an active community effort around the existing python.org Wiki sites, there are also people who are interested in improving these offerings. What worries me is that despite such activity and such interest, many people will continue to lament the lack of vitality (or whatever other metric) of the general python.org offering, whilst retaining a blind spot for the obvious contribution that the Wikis can make to such improvement efforts. I encourage people to use wiki.python.org a lot more, should they be looking to improve the wealth of information provided by the community. Paul -- http://mail.python.org/mailman/listinfo/python-list
Re: Social problems of Python doc [was Re: Python docs disappointing]
On Wed, 12 Aug 2009 20:23:27 -0700, rurpy wrote: That's no different from *any* major refactoring. The exact same problem exists for code as well as documentation. It's a solved problem for code, and it's a solved problem for documentation. Huh? I don't buy this at all. Code refactoring doesn't change the semantics of the program at all -- it simplifies the code that implements behavior without changing behavior. How does this apply to revising documentation? My apologies, I mis-wrote. Of course refactoring is inappropriate in this context. What I meant was a major redesign where the API may change. Except of course that documentation changes don't need to be concerned with backwards compatibility, except possibly to avoid breaking old links. [...] Yes it would. Most patches are ignored, because the dev team are overworked, and if they don't see the need for a patch, they won't approve it. I'm confused. If they weren't overworked, then they would approve patches they didn't see a need for? No. If they're overworked, they're less likely to spend time investigating patches which aren't immediately obvious that they're needed. And additionally, if the patch doesn't appear to be useful, it's unlikely to be approved. Why would it be? Or are you saying because they are overworked they fail to approve patches that should be approved? Invariably there will be good patches missed because they haven't been noticed. I am not sure how either supports the argument that the tracker is the best method of improving the docs. These are not arguments in favour of the tracker, these are realistic issues that any project of non-trivial size have to deal with. Virtually every project (not just software projects either) have to deal with the fact that there will be more things to do than resources to do them with. [...] No, submitting a tracker issue is a necessary but not sufficient step. Without a tracker issue, you're very unlikely to have people agree to replace the existing docs with your docs, although a PEP would probably do it. (A PEP is significantly more effort than raising a tracker issue.) Has there ever been a PEP for a doc change? Are you making a serious suggestion? I don't know if there ever has been, but as far as I know, there are two ways to get changes approved to Python: informal approval by somebody with check-in privileges, or formal approval on the basis of a PEP. If you can't get the first, then the second is an option, albeit unlikely. As long as every the docs sux complaint is met here with the standard responses that I've mentioned, But they aren't met with such a so-called standard response. I just looked through the first 70 or so messages in this thread and in this case I have agree with you, most of the responses were not what I called standard responses. There was one guy, a Steven D'Aprano early on that trotted out the, it's free software, fix it if you don't like it line, And I stand by it. If you're not helping to solve the problem, then what exactly are you doing? Even if you can't provide a patch, provide a bug report. What specifically is wrong with the docs? Be specific. Give examples. Explain why it is wrong. State your assumptions, e.g. what audience do you represent? If you do these things, you're helping. If you're just complaining, then you're not. We know that there are problems. We've said repeatedly that corrections and patches are welcome. We've repeatedly told you how to communicate your answer to the question of what should be done. None of this is good enough for you. I don't know what else you expect. You have been told repeatedly why your insistence that the tracker must be the only channel, is wrong. I don't understand why you can't understand that. (Generally only those in authority, bosses, parents, police, and the like, tell others what a situation is and have a right to demand that the subject accept it without question. I think you could find a more respectful and less authoritarian way of phrasing what you said above since you are not in a position of authority over me.) You're not my real dad!!! In the words of Jesse The Body Venture, I'm just telling it like it is. The tracker is the only practical way of getting doc changes accepted, for those without check-in privileges or the ear of someone with them. Me telling you this is no more an expression of authority than me telling you that the USA has 50 states. Of course I could be wrong. My understanding of the facts might be wrong, or I may not be in full possession of all the relevant facts. If so, I welcome correction. So please tell me, what other practical ways are there for an unprivileged person to get the official Python docs modified? -- Steven -- http://mail.python.org/mailman/listinfo/python-list
Re: Social problems of Python doc [was Re: Python docs disappointing]
A basic question in this thread is: Who will host the doc-wiki/whatever and how will it be linked to? If not hosted at python.org it can still be linked to from their docs, if allowed, possibly with 3rd level domain and re-direct. I host a number of commercial servers but I don't expect Guido to bless them with said links. If hosted at python.org it will require resources from the existing admins. If elsewhere then trusted admins and organization. If not linked to from python.org then it may well expire from lack of interest, as other seemingly nice attempts did. Ray Schumacher -- http://mail.python.org/mailman/listinfo/python-list
Re: Social problems of Python doc [was Re: Python docs disappointing]
ru...@yahoo.com wrote: Such a reorg is not a simple matter of moving a file from here to there. It will require a lot moving about of sections and a lot of word-smithing to glue them back together again in a coherent way. Concerning this particular issue, not everyone would agree that the doc sections in question are misplaced. In Python the distinction between builtin and library types is fairly blurry. There are advantages to having them all documented in one place -- when looking for info about a type, you don't have to try to guess whether it's considered built-in or not to know which manual to look in. -- Greg -- http://mail.python.org/mailman/listinfo/python-list
Re: Social problems of Python doc [was Re: Python docs disappointing]
On Tue, 11 Aug 2009 14:50:51 -0700, rurpy wrote: The issue tracker is fine for many things, but the process it provides is equivalent to peep-hole optimization. How does one submit a tracker issue for something like the overall organization of the docs (for example, the mis-placement of things like data- types in the library manual rather than the language manual)? The same way you would submit a tracker issue for anything. Documentation bug: Data types are misplaced in the library manual instead of the language manual. Suggested alternative: move page docs.python.org/xyz.html to abc.html But that's the problem. Such a reorg is not a simple matter of moving a file from here to there. It will require a lot moving about of sections and a lot of word-smithing to glue them back together again in a coherent way. That's no different from *any* major refactoring. The exact same problem exists for code as well as documentation. It's a solved problem for code, and it's a solved problem for documentation. In some order: Consensus that there is a problem that needs solving; Volunteer(s) to do the work; Somebody to take responsibility to check the changes in. Sometimes, in the face of apathy or disagreement (which may very well be justified), you have to at least partly solve the problem *before* people will agree that it needed to be solved. Welcome to the real world. A tracker issue, even one that was fairly specific about how things should be reorganized but which did not provide all the needed changes (a large patch) would almost certainly be ignored or rejected. Yes it would. Most patches are ignored, because the dev team are overworked, and if they don't see the need for a patch, they won't approve it. But providing a large patch raises two questions. How likely is it to be be accepted? (Something anyone would want to know before investing the time.) And how to actually do the work needed to generate it (it could be a very large amount of work for an individual and I don't think it can be broken down into small independent issues.) How is one to test the waters as to acceptability, or solicit help, if one simply submits a tracker issue? No, submitting a tracker issue is a necessary but not sufficient step. Without a tracker issue, you're very unlikely to have people agree to replace the existing docs with your docs, although a PEP would probably do it. (A PEP is significantly more effort than raising a tracker issue.) You also have to get attention from those with check-in privileges. If they approve your patches, you're done. If they don't approve them, or fail to respond, you can try convincing them, or taking it to the Python- Dev list and request somebody review your patches. If you have no patches, perhaps because you're unwilling to invest the effort without a guarantee that it will be treated seriously, then you need to get some sort of consensus among the relevant people that the problem is worth solving. Guess what? Sometimes others will disagree with you. What you see as the Worst. Docs. EVAR. may be seen as perfectly adequate, even excellent, by others. If this is the case, remember, Python isn't your product, you don't have veto over what goes into it. Feel free to publish your alternatives. Write a book. Go home and cry into your beer over it. Whatever. Sometimes you win, and sometimes you don't. This is the same process whether dealing with code or documentation. - if people are keen on a Python wiki, then by all means publish one, just don't expect the Python dev team to build and manage it for you; As luminous a Pythoneer as Fredrik Lundh set up a documentation wiki to collect user contributions but it has faded away. If he couldn't pull it off then I'd say most other attempts without the backing of python.org are almost certainly doomed to failure. Perhaps that's a good indication that a Python wiki *doesn't* fulfill a need in the community, and that despite what a few squeaky wheels think, the docs *are* doing a good job? As long as every the docs sux complaint is met here with the standard responses that I've mentioned, But they aren't met with such a so-called standard response. rather than, yes, they do have some problems, what do you think we should do about them?, We know that there are problems. We've said repeatedly that corrections and patches are welcome. We've repeatedly told you how to communicate your answer to the question of what should be done. None of this is good enough for you. I don't know what else you expect. If you won't put in the effort, and you won't put in the money, then it won't happen. Moaning that other people aren't putting in the money to hire team of professional writers isn't productive, and moaning that other people aren't putting in the effort to improve the docs isn't either. Eh? I have a computer filled with software that I put no money or
Re: Social problems of Python doc [was Re: Python docs disappointing]
On Tuesday 11 August 2009 19:53:16 Steven D'Aprano wrote: You want community input into the docs, but you're not willing to give that input except to bitch and moan and sook that the tracker is no good. wtf does the verb sook mean? I find: sook /sʊk/ Show Spelled Pronunciation [sook] Show IPA Use sook in a Sentence –noun 1. Australia and New Zealand. a timid, cowardly person, esp. a young person; crybaby. –interjection 2. Midland U.S. (used to summon cows from the pasture). Origin: 1890–95; prob. from earlier sense “calf reared by hand,” perh. suck(-calf), with sp. repr. N England, Scots pron. of suck (but earliest cited pron. of sook is (so̅o̅k)) Sometimes English drives me crazy. - Hendrik -- http://mail.python.org/mailman/listinfo/python-list
Re: Social problems of Python doc [was Re: Python docs disappointing]
On 12 Aug, 09:58, Steven D'Aprano ste...@remove.this.cybersource.com.au wrote: We know that there are problems. We've said repeatedly that corrections and patches are welcome. We've repeatedly told you how to communicate your answer to the question of what should be done. None of this is good enough for you. I don't know what else you expect. Maybe the problem is that although everyone welcomes contributions and changes (or says that they do), the mechanisms remain largely beyond criticism. Consequently, one sees occasional laments about there not being enough people contributing to Python core development and soul- searching about the reasons this might be so. If it were insisted that changes to, say, Wikipedia were to be proposed by submitting a patch or report for perusal by the editors and for future inclusion in some version of the project, the whole project would most likely be a shadow of its current self, and ambitions of large-scale collaborative editing in general would still be ridiculed. A free-for-all isn't likely to be the best solution for more actively edited Python documentation, but Wiki solutions undeniably provide a superior fast path for edits by trusted users to be incorporated and published in accessible end-user documentation. Almost every analysis of the current (and previous) documentation mechanisms has identified the editorial workflow as a bottleneck and then proceeded to replicate such a bottleneck in any proposed solution. I'm starting to believe that there's a certain snobbery about Wiki solutions which lead many people to develop all sorts of short-term, arcane solutions under the illusion that something super-special and customised is necessary and that they have to start virtually from scratch in order to cater to the ultra-special needs of the target audience; by the time they're done, no-one's interested any more, except to propose the next legacy system in the making. [...] That some of us choose to invest it somewhere other than Python does not deprive of of our right to point out problems in Python when we note them. Of course not. But it does mean that you won't be taken seriously, and you have no right to be taken seriously. That's an absurd position that has soured the reputation of numerous projects. When someone spends the time to write a bug report, they are often investing as much time and effort in something that they are able to in any productive sense. I make a habit of submitting bug reports to software distributions, typically so that the people who are responsible for the components involved can investigate the problem effectively. When the maintainers just close such reports or mark them with a number of different labels which mostly indicate that they consider those reports not worth their time, it sends the message that they consider their time to be vastly more important than their users, even though their users might have set aside an hour of their potentially busy schedule which might have meant sacrificing something else that should have taken higher priority (like time for sleeping, in my own personal experience). Thus, I've had the impression with some projects that I should be maintaining all sorts of stuff - the bootloader, the kernel, various desktop applications, Mozilla - all so that stuff actually gets fixed and that I'm not perceived as just another user whose bug reports aren't welcome. I don't find this reasonable at all when in many cases there *are* people getting paid to do these jobs. The Python core developers seem more attentive than in various other projects, but please let us not establish the delicate genius mentality that has infested other projects to the point that any criticism is automatically labelled as ungrateful whining by people who supposedly don't use the software, have an axe to grind, and who are apparent simpletons who don't understand the revolutionary vision of the project leadership. If you think throwing away goodwill is an acceptable way of silencing complaints, please take a look at just about any article about KDE 4 that permits reader comments to see how much goodwill can be lost and what effect that has on a project's reputation. Paul -- http://mail.python.org/mailman/listinfo/python-list
Re: Social problems of Python doc [was Re: Python docs disappointing]
On Wed, 12 Aug 2009 03:32:08 -0700, Paul Boddie wrote: On 12 Aug, 09:58, Steven D'Aprano ste...@remove.this.cybersource.com.au wrote: We know that there are problems. We've said repeatedly that corrections and patches are welcome. We've repeatedly told you how to communicate your answer to the question of what should be done. None of this is good enough for you. I don't know what else you expect. Maybe the problem is that although everyone welcomes contributions and changes (or says that they do), the mechanisms remain largely beyond criticism. Consequently, one sees occasional laments about there not being enough people contributing to Python core development and soul- searching about the reasons this might be so. If it were insisted that changes to, say, Wikipedia were to be proposed by submitting a patch or report for perusal by the editors and for future inclusion in some version of the project, the whole project would most likely be a shadow of its current self, and ambitions of large-scale collaborative editing in general would still be ridiculed. If Python had the tens of thousands of users, and hundreds of trusted (for some definition of trusted) editors, then Python could run using the same model as Wikipedia. The Wikipedia model is great, and I contribute to it myself. But Wikipedia gets its users from the entire population of web-users, because there's something of interest to everyone in Wikipedia. Interested in movies? There are Wikipedia pages for you to contribute to. Interested in medicine? There are pages you can help with. Interested in the history and development of the mechanical pencil? There's probably even a page for you. And if there isn't, you can create one. With tens of millions of web users, it's no surprise that Wikipedia can attract thousands of editors. But this does not apply to Python, which starts from a comparatively tiny population, primarily those interested in Python. Have a look at the Wikipedia page for Python. The Talk Page has comments from no more than *eight* people. The History stats suggest that, over seven years, only sixty-nine people have made more than a single edit to the page, most of them having made just two edits. Just 36 people have made more than two edits, and some of those are bots. Only one user, Lulu of the Lotus-Eaters (David Mertz), has made more than 100 edits. A free-for-all isn't likely to be the best solution for more actively edited Python documentation, but Wiki solutions undeniably provide a superior fast path for edits by trusted users to be incorporated and published in accessible end-user documentation. And the Python time-machine strikes again: http://wiki.python.org/moin/ That some of us choose to invest it somewhere other than Python does not deprive of of our right to point out problems in Python when we note them. Of course not. But it does mean that you won't be taken seriously, and you have no right to be taken seriously. That's an absurd position that has soured the reputation of numerous projects. When someone spends the time to write a bug report, they are often investing as much time and effort in something that they are able to in any productive sense. Firstly, in context, I wasn't talking to somebody who had made bug reports. I was talking to somebody whose only contribution, as near as I can tell, was to loudly complain that there are flaws in the Python documentation and insist that somebody else should fix them just the way he wants them fixed -- without being willing to even explain how he wants them fixed. Possibly the developers are expected to intuit from first principles what he wants. Secondly, the world is full of complainers who won't lift a finger to help but demand others help them. It may be unfair to tar everybody with the same brush, but life is to short and time to valuable to avoid making judgements as to who to pay attention to. Those who invest a lot of effort into providing patches get listened to closely; so do those who make good quality detailed bug reports. Those who just say It's broken, fix it don't. Sometimes that will mean that someone with genuinely good ideas will be ignored, but that's the price one pays for avoiding being drowned by a chorus of trivial, contradictory, vague and insubstantial complaints. If the Python Dev team paid attention to every post here claiming that Python has a bug when the bug was actually in the complainant's own code, we'd probably still be running Python 1.5. I make a habit of submitting bug reports to software distributions, typically so that the people who are responsible for the components involved can investigate the problem effectively. When the maintainers just close such reports or mark them with a number of different labels which mostly indicate that they consider those reports not worth their time, it sends the message that they consider their time to be
Re: Social problems of Python doc [was Re: Python docs disappointing]
Paul Boddie paul at boddie.org.uk writes: A free-for-all isn't likely to be the best solution for more actively edited Python documentation, but Wiki solutions undeniably provide a superior fast path for edits by trusted users to be incorporated and published in accessible end-user documentation. Agreed. I'm starting to believe that there's a certain snobbery about Wiki solutions which lead many people to develop all sorts of short-term, arcane solutions under the illusion that something super-special and customised is necessary and that they have to start virtually from scratch in order to cater to the ultra-special needs of the target audience; by the time they're done, no-one's interested any more, except to propose the next legacy system in the making. Not sure why you think it's snobbery... There are certain tacit expectations regarding the docs: - that they are versioned with the source tree (because, often, changes in documentation will be synchronized with changes in behaviour / functionality, because we must maintain documentation for several versions at once, because you want to use the same kind of merging that is used between different branches) - that they can be used offline, rebuilt in different formats, etc. - that you don't need a Web server (even locally) to navigate through them - that proposed changes are to be reviewed by maintainers (core developers) before they get actually committed I'm not sure of any existing wiki system which fits the bill. So, while I agree that the current situation can present a high threshold for occasional doc-only contributions, there doesn't seem to be a simple solution to improve things. -- http://mail.python.org/mailman/listinfo/python-list
Re: Social problems of Python doc [was Re: Python docs disappointing]
On 12 Aug, 14:08, Steven D'Aprano st...@remove-this- cybersource.com.au wrote: With tens of millions of web users, it's no surprise that Wikipedia can attract thousands of editors. But this does not apply to Python, which starts from a comparatively tiny population, primarily those interested in Python. Have a look at the Wikipedia page for Python. What does the Python entry on Wikipedia have to do with editing the Python documentation in a Wiki? Once everyone has agreed that the description of Python on Wikipedia is reasonable, there's not much point in editing it, is there? In contrast, there's a continuous stream of people who don't think Python's documentation is that great. [...] A free-for-all isn't likely to be the best solution for more actively edited Python documentation, but Wiki solutions undeniably provide a superior fast path for edits by trusted users to be incorporated and published in accessible end-user documentation. And the Python time-machine strikes again: http://wiki.python.org/moin/ And I suggested that the complainants use it as a starting point. [...] Oh dear me. You mean that they don't agree that YOUR time is more important than theirs??? What horrible people they must be, to expect you to sacrifice some of your sleep time just so *they* can get some sleep themselves!!! Who do they think they are??? That's quite an attempt to make my position more extreme than it actually is. I get people asking me to improve my own software, you know, and even if I don't have the time or inclination to do what they ask, I do spend time discussing it with them. Such people, including myself when I'm on the other side of the fence, appreciate more than just a brush-off and no: they don't insist that their own time be valued above anyone else's (as you would have me misrepresented); they just ask that their own efforts aren't treated as having no value because they're not part of the elite development team. You get various projects doing soul-searching about embracing the efforts of non-programmers, and the first port of call on that particular voyage is to not treat them like idiot consumers whose remarks can only be considered as mere heckling while the visionaries act out their flawless production. Paul P.S. The mention of social problems ties in with other remarks made recently, and I've increasingly found it more trouble than has been worthwhile to pursue Python-related matters of late. When one tries to encourage people to participate in improving various things, which usually means the community having to accept a degree of criticism, people claim that it's encouraging undesirable influences to point such critics in the right direction instead of showing them the door. When one tries to pursue such improvement matters oneself, people always have something to say about the choice of technology or whether they like the particular background colour being used or indeed have an opinion, typically shallow and negative, about anything but the task at hand, and there'll always be someone queuing up to dismantle anything that does get done at the first opportunity. In contrast, I've found other groups of people to be grateful for even modest technical assistance, and I know that such people are much more likely to get my support and input in the future than those who think that it's some kind of advantage to have potential contributors run the gauntlet of denial (that there are structural problems in their project), skepticism (that newcomers can have anything to contribute), discouragement (because any solution which doesn't validate someone's technology preferences must be criticised) and, indeed, outright hostility. One can always spend one's time doing something which isn't 100% enjoyable or 100% rewarding if one feels that the time is still being spent on something worthwhile. I'm getting the feeling that lots of Python-related stuff doesn't quite satisfy such criteria any more. -- http://mail.python.org/mailman/listinfo/python-list
Re: Social problems of Python doc [was Re: Python docs disappointing]
Paul Boddie wrote: [snip] One can always spend one's time doing something which isn't 100% enjoyable or 100% rewarding if one feels that the time is still being spent on something worthwhile. I'm getting the feeling that lots of Python-related stuff doesn't quite satisfy such criteria any more. I've been strongly considering volunteering to do Python work but this thread has put me off completely. I've time to spare as I only work part time due to long term health problems. However I don't feel that the time would be well spent on Python work, as I get the impression that a lot of it would go on cleaning some people's snotty noses, and on wiping other people's bottoms. I'll just wait until my normal voluntary work starts again next month after the summer break. Working with an extremely pleasant bunch of people hacking foreigners to death, that's more like it. See the following links should anyone be interested. http://www.dorsetforyou.com/index.jsp?articleid=386553 http://www.dorsetforyou.com/index.jsp?articleid=386598 -- Kindest regards. Mark Lawrence. -- http://mail.python.org/mailman/listinfo/python-list
Re: Social problems of Python doc [was Re: Python docs disappointing]
On Wed, 12 Aug 2009 06:24:18 -0700, Paul Boddie wrote: On 12 Aug, 14:08, Steven D'Aprano st...@remove-this- cybersource.com.au wrote: With tens of millions of web users, it's no surprise that Wikipedia can attract thousands of editors. But this does not apply to Python, which starts from a comparatively tiny population, primarily those interested in Python. Have a look at the Wikipedia page for Python. What does the Python entry on Wikipedia have to do with editing the Python documentation in a Wiki? Good question. I was responding to you mentioning Wikipedia as a possible role model for the Python docs. Once everyone has agreed that the description of Python on Wikipedia is reasonable, there's not much point in editing it, is there? And once we're all fabulously wealthy, there won't be any point in anyone working any more either! The problem for your argument is, even if it were correct, not everyone agrees the Python article is reasonable -- there were three edits made since the 7th of this month. And before that, there was a stream of 22 edits on the 5th, and another 25 edits since the 8th of July. Obviously the Python article is still in active development. Some of those edits were, apparently, vandalism, which gives yet another reason why the Wikipedia model is not necessarily the right model to follow. In contrast, there's a continuous stream of people who don't think Python's documentation is that great. And a great flood of those who think it's pretty good and gets the job done adequately, and a trickle of those who think it's perfect just the way it is. It's not the people who suggest improvements to the docs that are the problem, but the ones who insist that the docs are terrible, but aren't willing to do anything but complain. Oh, and trolls like ... I hesitate to mention his name in case he has a bot monitoring the list ... first name starts with X followed by ah, second name sounds like Mee ... who even if they make a few good points, they're lost in a sea of insults to others, arrogance and self-aggrandisement. And the Python time-machine strikes again: http://wiki.python.org/moin/ And I suggested that the complainants use it as a starting point. Sorry, I seem to have missed that. [...] Oh dear me. You mean that they don't agree that YOUR time is more important than theirs??? What horrible people they must be, to expect you to sacrifice some of your sleep time just so *they* can get some sleep themselves!!! Who do they think they are??? That's quite an attempt to make my position more extreme than it actually is. Well, you did raise the issue of the sacrifices you were making to report these bugs. All I did was exaggerate the attitude a tad. I get people asking me to improve my own software, you know, and even if I don't have the time or inclination to do what they ask, I do spend time discussing it with them. Such people, including myself when I'm on the other side of the fence, appreciate more than just a brush-off and no: they don't insist that their own time be valued above anyone else's Then you're incredibly lucky to attract a better class of end-users. In my experience, most end-users won't even spend the effort to describe the problem they're having beyond it doesn't work. And they usually misspell that. (as you would have me misrepresented); they just ask that their own efforts aren't treated as having no value because they're not part of the elite development team. You get various projects doing soul-searching about embracing the efforts of non-programmers, and the first port of call on that particular voyage is to not treat them like idiot consumers whose remarks can only be considered as mere heckling while the visionaries act out their flawless production. A noble vision, but wait until the idiot heckling consumers discover your software, then we'll see how much time you're prepared to give them. Paul P.S. The mention of social problems ties in with other remarks made recently, and I've increasingly found it more trouble than has been worthwhile to pursue Python-related matters of late. When one tries to encourage people to participate in improving various things, which usually means the community having to accept a degree of criticism, people claim that it's encouraging undesirable influences to point such critics in the right direction instead of showing them the door. Can you point me to a discussion where this has happened? When one tries to pursue such improvement matters oneself, people always have something to say about the choice of technology or whether they like the particular background colour being used You've discovered bike-shedding. or indeed have an opinion, typically shallow and negative, about anything but the task at hand, When you're agitating for change, anyone defending the status quo has opinions which are shallow and negative. When
Re: Social problems of Python doc [was Re: Python docs disappointing]
On 12 Aug, 17:08, Steven D'Aprano st...@remove-this- cybersource.com.au wrote: On Wed, 12 Aug 2009 06:24:18 -0700, Paul Boddie wrote: What does the Python entry on Wikipedia have to do with editing the Python documentation in a Wiki? Good question. I was responding to you mentioning Wikipedia as a possible role model for the Python docs. Yes, but claiming that only a few people want to edit a single entry on one site (admittedly a popular one) isn't the same as saying that few people would edit a documentation Wiki covering numerous different things. A bunch of people edit the existing Python Wiki now, although there's not that much direction behind it. [...] It's not the people who suggest improvements to the docs that are the problem, but the ones who insist that the docs are terrible, but aren't willing to do anything but complain. Oh, and trolls like ... I hesitate to mention his name in case he has a bot monitoring the list ... first name starts with X followed by ah, second name sounds like Mee ... who even if they make a few good points, they're lost in a sea of insults to others, arrogance and self-aggrandisement. Right, but those good points are still worth taking on board. There have been Xah Lee posts which have been relatively constructive, but when the only responses are from people who see the name and can't be bothered reading the message before issuing a stock he's a troll response, the tone is likely to remain vulgar from that point onwards. Xah Lee can be quite coherent and rational on comp.lang.lisp, which is more than can be said for a number of regulars on that group. [...] P.S. The mention of social problems ties in with other remarks made recently, and I've increasingly found it more trouble than has been worthwhile to pursue Python-related matters of late. When one tries to encourage people to participate in improving various things, which usually means the community having to accept a degree of criticism, people claim that it's encouraging undesirable influences to point such critics in the right direction instead of showing them the door. Can you point me to a discussion where this has happened? I won't name names as in some cases I've corresponded privately with various people who have been perceived to be trolls (as you put it above) and who have had the don't talk to them responses from various regulars. Some people criticise in apparently unacceptable ways for their own amusement, but most critics do so because they are unaware of any better way and aren't aware of the most effective methods to fix the issues that bother them, and this latter group is clearly invested in finding solutions because they could quite easily go and use something else. Certainly, I wouldn't spend my time repeatedly enumerating the problems with a piece of technology if no- one were interested in helping me do something about them. When one tries to pursue such improvement matters oneself, people always have something to say about the choice of technology or whether they like the particular background colour being used You've discovered bike-shedding. or indeed have an opinion, typically shallow and negative, about anything but the task at hand, When you're agitating for change, anyone defending the status quo has opinions which are shallow and negative. When you're happy with the status quo, possibly even for good, rational reasons and not just because you're a shallow-minded, ignorant, know-nothing nay-sayer, it's those agitating for change who have shallow and negative opinions. It's such a bother trying to determine who is right, so I prefer to just accuse the other guy of being shallow and negative rather than try to understand his point of view. I find it saves time in the long run. I can expand what I've written to just about any project, improvement or otherwise, where there may not be an existing solution that anyone actually supports or is willing to use. And still, if you give people something they could use (which is better than effectively nothing), my experience is that in some communities your work, however trivial, will be appreciated. But I get the impression that in Python-related communities, it's all Why didn't you use XYZ? or What a toy! instead. [...] There seems to be a hidden assumption in your sentence that there *are* structural problems in the project. Let me assume that maybe the barriers aren't really that bad for Python documentation; that anyone who is really going to care about submitting something will jump through the hoops and deliver something that can be merged by the core developers. Even then, there's going to be a whole class of improvements that won't get made by outsiders and will fall on the editors to make. Now, more often than not, the people who are already the most overworked are precisely those in the position of reviewing and merging changes (as well as making their own), and surely
Re: Social problems of Python doc [was Re: Python docs disappointing]
Paul Boddie wrote: On 12 Aug, 17:08, Steven D'Aprano st...@remove-this- cybersource.com.au wrote: It's not the people who suggest improvements to the docs that are the problem, but the ones who insist that the docs are terrible, but aren't willing to do anything but complain. Oh, and trolls like ... I hesitate to mention his name in case he has a bot monitoring the list ... first name starts with X followed by ah, second name sounds like Mee ... who even if they make a few good points, they're lost in a sea of insults to others, arrogance and self-aggrandisement. Right, but those good points are still worth taking on board. The responsibility for communication is shared. How much to each party varies by circumstance (employer/employee, rank, volunteer, etc.). For myself, his posts are automatically deleted -- my time is precious to me. ~Ethan~ -- http://mail.python.org/mailman/listinfo/python-list
Re: Social problems of Python doc [was Re: Python docs disappointing]
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
Re: Social problems of Python doc [was Re: Python docs disappointing]
[Xah Lee] i've wrote several articles about this issue, total time spend on this is probably more than 2 months full-time work. See: • Python Documentation Problems http://xahlee.org/perl-python/python_doc_index.html I just read you post. You did devote a substantial amount of time to the project. Some of your criticisms are valid. Wish you had posted patches, I think many of them would have been accepted. Since you wrote this a few years ago, many examples have been added to the docs and more are forthcoming. I often receive thank you emails for 2 particular articles, which are most frequently google searched as indicated by my weblog: • Python Doc Problem Example: gzip http://xahlee.org/perl-python/python_doc_gzip.html • Python Doc Problem Example: sort() http://xahlee.org/perl-python/python_doc_sort.html • Sorting in Python and Perl http://xahlee.org/perl-python/sort_list.html Some are the criticisms are valid; others seem off-base. Here are a few thoughts on list.sort() for those who are interested: * The key= and reversed= parameters are not intended for special cases, leaving cmp= for the general case. They were intended to be full replacements. In Python3.x, the cmp function is gone. * The interaction of the key= and cmp= functions can be made to interact (the key function is first applied to every element and the cmp function then gets applied to the results of the key function). This isn't a normal or intended use case, so the docs don't delve into the subject. * The reversed parameter does more than list.sort() followed by list.reverse(). It also preserves stability in the event of equal keys: sorted([(1,2), (1,3)], key=itemgetter(0), reverse=True) [(1,2), (1,3)] So it was not correct to say that the following are equivalent: li.sort(lambda x, y: cmp(x[1],y[1]), reverse=True) li.sort(lambda x, y: cmp(y[1],x[1])) * We should link the sorted() and list.sort() docs to the sorting how-to (with a fuller discussion on the art of sorting including a discussion of operator.itemgetter() and operator.attrgetter() which were designed to work with the key= parameter. Raymond -- http://mail.python.org/mailman/listinfo/python-list
Re: Social problems of Python doc [was Re: Python docs disappointing]
On Aug 12, 1:27 pm, Raymond Hettinger pyt...@rcn.com wrote: (snip) * 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... Yes, if many people have problems with the docs then that must be a *clue* to some underling problem in the way the docs are presented. Whether its from misinfomation, misguidance, or just plain misunderstanding on the reader's part that does not matter. There are problems and we need the feedback from everybody noob-to-pro on how to fix this conundrum. One thing that some naysayers may forget is the fact that these noobs most likely have no idea *how*, *when*, or *where* to voice a complaint so they just move on to the next language or suffer with an incomplete understanding of the language and/or proper python idioms. I would say the complaints that this list has seen concerning docs only scratches the surface of the huge underling issues that face us here! 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. Eloquent and beautiful a paragraph that was Raymond. Why, because common sense is just so damn beautiful. Keep the docs clean of personal opinions and just give us the facts people. Who cares about the history of OOP --Google it!-- i want to read about using Python. Give me the nitty-gritty-down-and-dirty-facts that relate to Python syntax and structure, and only the facts, in the most strait forward and common sense way so i can get on to actually writing some code! If you seek self gratification visit c.l.py and vent away, everyone else seems to. -- http://mail.python.org/mailman/listinfo/python-list
Re: Social problems of Python doc [was Re: Python docs disappointing]
[Raymond Hettinger] Here are a few thoughts on list.sort() for those who are interested: After one more reading of Xah Lee's posts on the documentation for sort, here are couple more thoughts: * The reason that list.sort() allows None for the cmp parameter is not so that you can write list.sort(None). It was put there to make it easier for people writing function definitions where the cmp function is a possible argument: def sort_and_chop(seq, maxlen, cmp=None): s = seq[:] s.sort(cmp) # needs to accept None as a possible argument return s[:maxlen] * The reason for implementing the key= parameter had nothing to do with limitations of Python's compiler. Instead, it was inspired by the decorate-sort-undecorate pattern. Raymond -- http://mail.python.org/mailman/listinfo/python-list
Re: Social problems of Python doc [was Re: Python docs disappointing]
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: In short, most doc requests that get rejected are requests that didn't actually improve the documentation. Raymond Thanks for your very eloquent and cohernt response that in my opinion helps to explain many of the problems, either real or perceived, with the Python documentation -- Stanley C. Kitching Human Being Phoenix, Arizona -- http://mail.python.org/mailman/listinfo/python-list
Re: Social problems of Python doc [was Re: Python docs disappointing]
On 08/12/2009 01:58 AM, Steven D'Aprano wrote: On Tue, 11 Aug 2009 14:50:51 -0700, rurpy wrote: The issue tracker is fine for many things, but the process it provides is equivalent to peep-hole optimization. How does one submit a tracker issue for something like the overall organization of the docs (for example, the mis-placement of things like data- types in the library manual rather than the language manual)? The same way you would submit a tracker issue for anything. Documentation bug: Data types are misplaced in the library manual instead of the language manual. Suggested alternative: move page docs.python.org/xyz.html to abc.html But that's the problem. Such a reorg is not a simple matter of moving a file from here to there. It will require a lot moving about of sections and a lot of word-smithing to glue them back together again in a coherent way. That's no different from *any* major refactoring. The exact same problem exists for code as well as documentation. It's a solved problem for code, and it's a solved problem for documentation. Huh? I don't buy this at all. Code refactoring doesn't change the semantics of the program at all -- it simplifies the code that implements behavior without changing behavior. How does this apply to revising documentation? It may be true that some of the same techniques applicable to maintaining code are applicable to documentation but I need a lot more than your assertion to believe they are as equivalent as you seem to be claiming. In some order: Consensus that there is a problem that needs solving; Volunteer(s) to do the work; Somebody to take responsibility to check the changes in. That's not refactoring as I understand it -- that is making a large change. I don't see that that addresses the problem of getting a large patch approved or the other issues I mentioned. Sometimes, in the face of apathy or disagreement (which may very well be justified), you have to at least partly solve the problem *before* people will agree that it needed to be solved. Welcome to the real world. A tracker issue, even one that was fairly specific about how things should be reorganized but which did not provide all the needed changes (a large patch) would almost certainly be ignored or rejected. Yes it would. Most patches are ignored, because the dev team are overworked, and if they don't see the need for a patch, they won't approve it. I'm confused. If they weren't overworked, then they would approve patches they didn't see a need for? Or are you saying because they are overworked they fail to approve patches that should be approved? I am not sure how either supports the argument that the tracker is the best method of improving the docs. But providing a large patch raises two questions. How likely is it to be be accepted? (Something anyone would want to know before investing the time.) And how to actually do the work needed to generate it (it could be a very large amount of work for an individual and I don't think it can be broken down into small independent issues.) How is one to test the waters as to acceptability, or solicit help, if one simply submits a tracker issue? No, submitting a tracker issue is a necessary but not sufficient step. Without a tracker issue, you're very unlikely to have people agree to replace the existing docs with your docs, although a PEP would probably do it. (A PEP is significantly more effort than raising a tracker issue.) Has there ever been a PEP for a doc change? Are you making a serious suggestion? You also have to get attention from those with check-in privileges. If they approve your patches, you're done. If they don't approve them, or fail to respond, you can try convincing them, or taking it to the Python- Dev list and request somebody review your patches. If you have no patches, perhaps because you're unwilling to invest the effort without a guarantee that it will be treated seriously, then you need to get some sort of consensus among the relevant people that the problem is worth solving. You are again describing the current process, not the issue of whether the current process is the optimal one or not. And while I would never expect a guarantee that a particular submission would be accepted, I think I would need, if not a guarantee, at least a high expectation that a submission would be treated seriously before I invested a large amount of work in it. Guess what? Sometimes others will disagree with you. What you see as the Worst. Docs. EVAR. may be seen as perfectly adequate, even excellent, by others. If this is the case, remember, Python isn't your product, you don't have veto over what goes into it. Feel free to publish your alternatives. Write a book. Go home and cry into your beer over it. Whatever. Sometimes you win, and sometimes you don't. Right, this is obvious. But the other side of that coin is that if people who see problems with the docs
Re: Social problems of Python doc [was Re: Python docs disappointing]
Raymond Hettinger wrote: 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. The summary that follows accords with my experiences and observations. Perhaps you could add it to the Wiki. ISTM that important corrections (when the docs are clearly in error) tend to get made right away. Many within a day. I have seen this with both some of my suggestions and others. What is more interesting are the doc requests that get rejected and why: One of my suggestions was postponed pending discussion on PyDev of the underlying issue, which I have not initiated yet. Another Georg accepted in principle but awaits me taking the time to write a fleshed out replacement text. * 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). I doubt anyone can *really* understand the problem of organizing a book's worth in technical information into coherent order until they have actually tried to do so. 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:
Re: Social problems of Python doc [was Re: Python docs disappointing]
Paul Boddie wrote: Right, but those good points are still worth taking on board. There have been Xah Lee posts which have been relatively constructive, The last time that he did do so that I read, I responded rationally like I would with any other normal post. He responded with foul insults. End of discussion. when the only responses are from people who see the name and can't be bothered reading the message before issuing a stock he's a troll False premise. response, the tone is likely to remain vulgar from that point onwards. He was vulgar even when I did ignore the name and did bother to read and write (not 'issue') a specific response. He has also 'blown' opportunities on the py-dev list. tjr -- http://mail.python.org/mailman/listinfo/python-list
Re: Social problems of Python doc [was Re: Python docs disappointing]
r rt8396 at gmail.com writes: On Aug 9, 11:02 pm, David Lyon david.l...@preisshare.net wrote: Since you're talking about documentation, which is a part of python, don't you think you should be discussing it on python-dev ? Yea, them's be a friendly bunch to noob ideas ;). Hey i got a better idea, lets go to the IRS and see if we can persuade them to stop taxing us... You know, the most interesting thing in this thread is certainly its title : « Social problems of Python doc » Yes, the little social problem here should be clear: if you have complaints to voice or improvements to suggest to the Python docs, you should do so on the issue tracker (*). For most topics, this is the only reasonable way to signal problems to the Python developers community, and so it is in most free software / open source projects. Just because you are able to write tongue-in-cheek (**) comments on python-list or, even worse, on a third party website, and generate a long thread about how Python doc (supposedly) s*cks 1) doesn't mean there is a legitimate issue (we all know how people can quickly inflame about empty subjects) 2) even though there can be a legitimate issue, doesn't mean Python developers will go out of their way and parse the entirety of the messages to find potentially useful data in them. The bug tracker is the place for this, and it's your task, if you want to help, to submit suggestions in it. FYI, the Python doc is very actively maintained nowadays, and bug reports /are/ taken into account. If you think you've got a lot of time for ranting about how the doc sucks, but don't want to spend the couple of minutes needed to post issues on the bug tracker, it speaks a lot about your motivation. Admittedly, in every successful community, there are attention seekers who are not interested in actual participation. (*) http://bugs.python.org (**) yes, humour is fine, but it doesn't replace actual, informational content Antoine. -- http://mail.python.org/mailman/listinfo/python-list
Re: Social problems of Python doc [was Re: Python docs disappointing]
Antoine Pitrou wrote: r rt8396 at gmail.com writes: On Aug 9, 11:02 pm, David Lyon david.l...@preisshare.net wrote: Since you're talking about documentation, which is a part of python, don't you think you should be discussing it on python-dev ? Yea, them's be a friendly bunch to noob ideas ;). Hey i got a better idea, lets go to the IRS and see if we can persuade them to stop taxing us... You know, the most interesting thing in this thread is certainly its title : « Social problems of Python doc » Yes, the little social problem here should be clear: if you have complaints to voice or improvements to suggest to the Python docs, you should do so on the issue tracker (*). For most topics, this is the only reasonable way to signal problems to the Python developers community, and so it is in most free software / open source projects. Just because you are able to write tongue-in-cheek (**) comments on python-list or, even worse, on a third party website, and generate a long thread about how Python doc (supposedly) s*cks 1) doesn't mean there is a legitimate issue (we all know how people can quickly inflame about empty subjects) 2) even though there can be a legitimate issue, doesn't mean Python developers will go out of their way and parse the entirety of the messages to find potentially useful data in them. The bug tracker is the place for this, and it's your task, if you want to help, to submit suggestions in it. FYI, the Python doc is very actively maintained nowadays, and bug reports /are/ taken into account. If you think you've got a lot of time for ranting about how the doc sucks, but don't want to spend the couple of minutes needed to post issues on the bug tracker, it speaks a lot about your motivation. Admittedly, in every successful community, there are attention seekers who are not interested in actual participation. (*) http://bugs.python.org (**) yes, humour is fine, but it doesn't replace actual, informational content Antoine. Thank you for this fine, cultured, reasonable response. Seriously!!! -- Kindest regards. Mark Lawrence. -- http://mail.python.org/mailman/listinfo/python-list
Re: Social problems of Python doc [was Re: Python docs disappointing]
On 08/11/2009 01:47 AM, Antoine Pitrou wrote: rrt8396at gmail.com writes: On Aug 9, 11:02 pm, David Lyondavid.l...@preisshare.net wrote: Since you're talking about documentation, which is a part of python, don't you think you should be discussing it on python-dev ? Yea, them's be a friendly bunch to noob ideas ;). Hey i got a better idea, lets go to the IRS and see if we can persuade them to stop taxing us... You know, the most interesting thing in this thread is certainly its title : « Social problems of Python doc » Yes, the little social problem here should be clear: if you have complaints to voice or improvements to suggest to the Python docs, you should do so on the issue tracker (*). For most topics, this is the only reasonable way to signal problems to the Python developers community, and so it is in most free software / open source projects. the *only* reasonable way? That's clearly wrong (unless you want to wiggle in the room provided by reasonable or most). There is discussion on the dev list, there is discussion here. The issue tracker is fine for many things, but the process it provides is equivalent to peep-hole optimization. How does one submit a tracker issue for something like the overall organization of the docs (for example, the mis-placement of things like data- types in the library manual rather than the language manual)? The big problem with the docs is poor writing (this includes not using examples when they can help explain something more clearly than verbiage alone). It is understandable why this should be so -- most programmers are good at and enjoy programming, not writing and the python community is, say, about 99.9% programmers. This is why all the attempts (at least that I've noticed) are programming focused -- build a wiki, write a new doc processing framework, etc. Unfortunately none of those addresses the real problem -- the need for clear, well written, well organized *content*. I don't see how telling people to submit tracker issues will solve this problem. I can rewrite some section so it sounds good to me, but likely it will be just as bad (perhaps in different ways) that what is there. The post that started this thread proposed something like paying professional writers to improve the docs. This may or may not be a practical suggestion. But the immediate response it engendered was an auto-immune-like group response: the docs are great already, don't complain, fix them yourself, yada, yada; the same response that any criticism of free software produces. It's really too bad the the python community can't seriously discuss ways to improves the docs. There are other possibilities for instance the Fedora Docs project (can't say I'm impressed by what they've produced but that doesn't mean their model is useless). There is a need for an approval process managed by someone who actually understands what good technical writing is. And perhaps editors who can polish or work with programmers who provide the raw technical description of some module. Some kind of higher level more global process is the only way I can see that the docs will be improved to any sort or professional standard. I don't see how issues like this will be addressed by submitting tracker items. Personally, I have given up on this issue. The social factors involved really pretty much determine that the Python docs will never reach a very high quality -- that's just the way it is and I've come to accept that. -- http://mail.python.org/mailman/listinfo/python-list
Re: Social problems of Python doc [was Re: Python docs disappointing]
On Tue, 11 Aug 2009 07:57:28 -0700, rurpy wrote: On 08/11/2009 01:47 AM, Antoine Pitrou wrote: rrt8396at gmail.com writes: On Aug 9, 11:02 pm, David Lyondavid.l...@preisshare.net wrote: Since you're talking about documentation, which is a part of python, don't you think you should be discussing it on python-dev ? Yea, them's be a friendly bunch to noob ideas ;). Hey i got a better idea, lets go to the IRS and see if we can persuade them to stop taxing us... You know, the most interesting thing in this thread is certainly its title : « Social problems of Python doc » Yes, the little social problem here should be clear: if you have complaints to voice or improvements to suggest to the Python docs, you should do so on the issue tracker (*). For most topics, this is the only reasonable way to signal problems to the Python developers community, and so it is in most free software / open source projects. the *only* reasonable way? That's clearly wrong (unless you want to wiggle in the room provided by reasonable or most). There is discussion on the dev list, there is discussion here. Discussion here is spitting into the wind. The noise-to-signal ratio is high enough that the people who can fix an issue aren't likely to see it here. Unless somebody raises a report in the bug tracker, it will go nowhere, fast. The same happens for issues on the dev list: I can't count how many times people there have said put it in the bug tracker, or it will be forgotten. The issue tracker is fine for many things, but the process it provides is equivalent to peep-hole optimization. How does one submit a tracker issue for something like the overall organization of the docs (for example, the mis-placement of things like data- types in the library manual rather than the language manual)? The same way you would submit a tracker issue for anything. Documentation bug: Data types are misplaced in the library manual instead of the language manual. Suggested alternative: move page docs.python.org/xyz.html to abc.html The big problem with the docs is poor writing (this includes not using examples when they can help explain something more clearly than verbiage alone). There's a difference between insufficiently good writing and poor writing: think of grading the docs, where 100 is perfect in every way and -100 is perfectly awful in every possible way. (It's not a linear scale.) A score of 0 is mediocre, just barely acceptable. Poor writing has a negative score. In my opinion, Python's docs are perhaps a 40 or 50, significantly better than most technical docs I've seen. [...] I can rewrite some section so it sounds good to me, but likely it will be just as bad (perhaps in different ways) that what is there. Bug reports are valuable even if you don't have the skills to provide a patch. Bug reports with patches are even more valuable, but that doesn't mean that the failure to provide a patch *necessarily* dooms your report to oblivion. The post that started this thread proposed something like paying professional writers to improve the docs. This may or may not be a practical suggestion. But the immediate response it engendered was an auto-immune-like group response: the docs are great already, don't complain, fix them yourself, yada, yada; the same response that any criticism of free software produces. I haven't seen any such knee-jerk responses. What I've seen is a set of sensible, *practical* advice: - complaining on its own, especially here, is pointless; - Python is a community effort, if you see something that needs fixing, do something about it; - many of us DON'T want arbitrary people correcting the official docs without oversight, and believe that would be a disaster (arbitrary people aren't give check-in privileges to add code to Python's standard library, nor should they be given check-in privileges to add docs); - if people are keen on a Python wiki, then by all means publish one, just don't expect the Python dev team to build and manage it for you; - bug reports and patches to the docs are ALWAYS welcome, even if they are rejected; - if you don't have the skills to fix a bug (including doc bugs), an alternative is to pay somebody else to do so instead. It's really too bad the the python community can't seriously discuss ways to improves the docs. There are other possibilities for instance the Fedora Docs project (can't say I'm impressed by what they've produced but that doesn't mean their model is useless). There is a need for an approval process managed by someone who actually understands what good technical writing is. And perhaps editors who can polish or work with programmers who provide the raw technical description of some module. Yes, you're correct. [sarcasm] Now that we've agreed on what needs to be done, the problem is solved!!! [end sarcasm] Some kind of higher level more global process is the only way I can
Re: Social problems of Python doc [was Re: Python docs disappointing]
Steven D'Aprano st...@remove-this-cybersource.com.au writes: - if people are keen on a Python wiki, then by all means publish one, just don't expect the Python dev team to build and manage it for you; There are already some nice ones at: http://en.wikibooks.org/wiki/Python -- http://mail.python.org/mailman/listinfo/python-list
Re: Social problems of Python doc [was Re: Python docs disappointing]
On 08/11/2009 11:53 AM, Steven D'Aprano wrote: On Tue, 11 Aug 2009 07:57:28 -0700, rurpy wrote: On 08/11/2009 01:47 AM, Antoine Pitrou wrote: rrt8396at gmail.com writes: On Aug 9, 11:02 pm, David Lyondavid.l...@preisshare.net wrote: Since you're talking about documentation, which is a part of python, don't you think you should be discussing it on python-dev ? Yea, them's be a friendly bunch to noob ideas ;). Hey i got a better idea, lets go to the IRS and see if we can persuade them to stop taxing us... You know, the most interesting thing in this thread is certainly its title : « Social problems of Python doc » Yes, the little social problem here should be clear: if you have complaints to voice or improvements to suggest to the Python docs, you should do so on the issue tracker (*). For most topics, this is the only reasonable way to signal problems to the Python developers community, and so it is in most free software / open source projects. the *only* reasonable way? That's clearly wrong (unless you want to wiggle in the room provided by reasonable or most). There is discussion on the dev list, there is discussion here. Discussion here is spitting into the wind. The noise-to-signal ratio is high enough that the people who can fix an issue aren't likely to see it here. Unless somebody raises a report in the bug tracker, it will go nowhere, fast. The point isn't always to gain a core developer's attention -- sometimes it is to figure out a good approach before proposing something concrete. The same happens for issues on the dev list: I can't count how many times people there have said put it in the bug tracker, or it will be forgotten. On the contrary, there are many issues raised there that are discussed there or result in the response, take it to python- ideas. Not every issue to so well-baked that it is ready for a tracker issue with patch. There are some things that need discussion before investing a lot of effort in them. The issue tracker is fine for many things, but the process it provides is equivalent to peep-hole optimization. How does one submit a tracker issue for something like the overall organization of the docs (for example, the mis-placement of things like data- types in the library manual rather than the language manual)? The same way you would submit a tracker issue for anything. Documentation bug: Data types are misplaced in the library manual instead of the language manual. Suggested alternative: move page docs.python.org/xyz.html to abc.html But that's the problem. Such a reorg is not a simple matter of moving a file from here to there. It will require a lot moving about of sections and a lot of word-smithing to glue them back together again in a coherent way. A tracker issue, even one that was fairly specific about how things should be reorganized but which did not provide all the needed changes (a large patch) would almost certainly be ignored or rejected. But providing a large patch raises two questions. How likely is it to be be accepted? (Something anyone would want to know before investing the time.) And how to actually do the work needed to generate it (it could be a very large amount of work for an individual and I don't think it can be broken down into small independent issues.) How is one to test the waters as to acceptability, or solicit help, if one simply submits a tracker issue? The big problem with the docs is poor writing (this includes not using examples when they can help explain something more clearly than verbiage alone). There's a difference between insufficiently good writing and poor writing: think of grading the docs, where 100 is perfect in every way and -100 is perfectly awful in every possible way. (It's not a linear scale.) A score of 0 is mediocre, just barely acceptable. Poor writing has a negative score. In my opinion, Python's docs are perhaps a 40 or 50, significantly better than most technical docs I've seen. There is no objective way of rating docs. My evaluation results in part from the fact that I was able to learn Perl using only the man pages. I seriously attempted the same with the supposedly easier-to-learn Python but was not able to and had to resort to other web resources and buying Beazly's book. Before you reply that tutorials are for learning, not reference manuals, I will disagree. A well written reference manual will provide all the information needed to understand a language (albeit arranged differently than the linear form of a tutorial), and I have learned several languages in addition to Perl from their reference materials. Which is why I attribute my failure to do so with Python to be the docs' fault. [...] I can rewrite some section so it sounds good to me, but likely it will be just as bad (perhaps in different ways) that what is there. Bug reports are valuable even if you don't have the skills to provide a patch. Bug reports with patches are
Re: Social problems of Python doc [was Re: Python docs disappointing]
On 11 Aug, 23:50, ru...@yahoo.com wrote: However, were the Python docs site to provide a wiki, along with a mechanism to migrate suggestions developed on the wiki into the docs, it might well be a viable (and easier because of the wysiwyg effect) way of improving the docs. As other have pointed out, Postgresql, PHP, and Haskell have done so. Now maybe there are good reasons not to do that. But your hand- waving is not one of them. I think you make some good points, although I don't have time to respond to all of them. Certainly, the documentation situation with Python is not ideal; otherwise, people would not be complaining about it so frequently. I recommend going to the existing Wiki and looking at what there is already: http://wiki.python.org/moin/Documentation http://wiki.python.org/moin/CategoryDocumentation Sadly, I don't think you'll find much to work with, apart from the occasional attempt to make an annotated version of the existing documentation: http://wiki.python.org/moin/PythonLibraryReference So my next recommendation is to either use the existing Wiki infrastructure or to ask for a separate Wiki for the purpose of reworking the documentation. You could either take the existing documentation, which I believe is now restructured text, and just drop that into the Wiki with the appropriate format directives (for later reworking in Wiki format, perhaps), or you could start afresh and tackle some of the more serious issues head on. I can see benefits to just starting from scratch. Perhaps the licensing should be more explicit than the existing material on the Wiki so that the documentation produced could be freely distributed without uncertainty, but the outcome would hopefully be something that stands on its own as an alternative or a replacement to the conventional documentation. Paul -- http://mail.python.org/mailman/listinfo/python-list
Re: Social problems of Python doc [was Re: Python docs disappointing]
At 03:08 PM 8/11/2009, you wrote: I recommend going to the existing Wiki and looking at what there is already: http://wiki.python.org/moin/Documentation http://wiki.python.org/moin/CategoryDocumentation I also can't see how to get from http://wiki.python.org/moin/Documentation to http://wiki.python.org/moin/CategoryDocumentation, for one... Sadly, I don't think you'll find much to work with, apart from the occasional attempt to make an annotated version of the existing documentation: http://wiki.python.org/moin/PythonLibraryReference The library reference above needs a link to Modules (and the link to Andrew's pages are now dead - http://pydoc.amk.ca/frame.htmlhttp://pydoc.amk.ca/frame.html) What I've always looked for and Google constantly for, is a main language version of the features of http://www.scipy.org/Cookbook and http://code.activestate.com/recipes/langs/python/, with module level organization. At least users can submit something at Activestate. The issue there (and at Scipy) is that I usually want an example illustrating some method, and that's not how it's organized (but is at those Other language sites), so I still need to search at Scipy, or do http://www.google.com/search?q=site%3Ascipy.org+foo -- http://mail.python.org/mailman/listinfo/python-list
Re: Social problems of Python doc [was Re: Python docs disappointing]
On Aug 11, 3:08 pm, Paul Boddie p...@boddie.org.uk wrote: Certainly, the documentation situation with Python is not ideal; otherwise, people would not be complaining about it so frequently. I will not take an opinion on whether Python's documentation is ideal (more on why below) but I will opine that the conclusion doesn't follow from your premise. People's expectations of what documentation should be are too different, there will always be people who aren't pleased. IOW, there is no ideal. For example, kj (who started this mess of thread) complained that pydoc didn't give exhaustive usage documentation. In contrast, I think pydoc gives too much information. I would rather have only the bare minimum; I don't want to pan through ten paragraphs just to see what the fifth argument is. So who's right? No one, there is no right. Unfortunately some people can't or won't respect that opinions differ; they have to take perceived defects in the docs personally. Carl Banks -- http://mail.python.org/mailman/listinfo/python-list
Re: Social problems of Python doc [was Re: Python docs disappointing]
On 11 Aug, 11:37 pm, pavlovevide...@gmail.com wrote: I will not take an opinion on whether Python's documentation is ideal (more on why below) but I will opine that the conclusion doesn't follow from your premise. People's expectations of what documentation should be are too different, there will always be people who aren't pleased. IOW, there is no ideal. For example, kj (who started this mess of thread) complained that pydoc didn't give exhaustive usage documentation. In contrast, I think pydoc gives too much information. I would rather have only the bare minimum; I don't want to pan through ten paragraphs just to see what the fifth argument is. So who's right? No one, there is no right. Unfortunately some people can't or won't respect that opinions differ; they have to take perceived defects in the docs personally. This is right on. Excellent point, Carl. Jean-Paul -- http://mail.python.org/mailman/listinfo/python-list
Re: Social problems of Python doc [was Re: Python docs disappointing]
On Aug 11, 4:08 pm, Paul Boddie p...@boddie.org.uk wrote: On 11 Aug, 23:50, ru...@yahoo.com wrote: However, were the Python docs site to provide a wiki, along with a mechanism to migrate suggestions developed on the wiki into the docs, it might well be a viable (and easier because of the wysiwyg effect) way of improving the docs. As other have pointed out, Postgresql, PHP, and Haskell have done so. Now maybe there are good reasons not to do that. But your hand- waving is not one of them. [...] I can see benefits to just starting from scratch. Perhaps the licensing should be more explicit than the existing material on the Wiki so that the documentation produced could be freely distributed without uncertainty, but the outcome would hopefully be something that stands on its own as an alternative or a replacement to the conventional documentation. A couple years ago I actually did give a half-assed try to rewriting the doc. I got the doc source downloaded and buildable with the intent of rewriting in bits and pieces as I had occasion to use (and find problems with) various parts. Not knowing latex, I stupidly got side- tracked trying to convert it to docbook which I was more interested in. After I gave up on that and went back to latex, I found merging changes from Python into my source (a little of which was heavily modified by this time) to be very time consuming. And eventually the Python side was changed to REST putting an end to my effort which by that time were already pretty minimal. I concluded that the rewrite I was trying to do was comparable to writing a Python book, and too ambitious for one person working on it 5 hrs/week. And of course I am not any better writer (probably worse) than the average Python programmer. Which is the problem with using a wiki -- unless good writers contribute, I see no reason to expect much better results than already exist. But maybe I am too pessimistic... -- http://mail.python.org/mailman/listinfo/python-list
Re: Social problems of Python doc [was Re: Python docs disappointing]
Carl Banks pavlovevide...@gmail.com writes: On For example, kj (who started this mess of thread) complained that pydoc didn't give exhaustive usage documentation. In contrast, I think pydoc gives too much information. I would rather have only the bare minimum; I don't want to pan through ten paragraphs just to see what the fifth argument is. The problem is that it doesn't sufficiently separate the carefully written useful stuff from the automatically generated useless stuff. -- http://mail.python.org/mailman/listinfo/python-list
Re: Social problems of Python doc [was Re: Python docs disappointing]
On Aug 9, 10:02 pm, David Lyon david.l...@preisshare.net wrote: ... Before you do that, you should clearly work out in your own mind how you think things need to improve. It's not good enough just saying this or that is bad without having specific ideas on what needs to change. ''' He did. Did you read, for example, the critique of the gzip docs for which he gave the url http://xahlee.org/perl-python/python_doc_gzip.html There were some things I might not completely agree with there, but basically, I thought it was right on, including his suggestions on how to improve it. -- http://mail.python.org/mailman/listinfo/python-list
Re: Social problems of Python doc [was Re: Python docs disappointing]
On Aug 9, 11:02 pm, David Lyon david.l...@preisshare.net wrote: Since you're talking about documentation, which is a part of python, don't you think you should be discussing it on python-dev ? Yea, them's be a friendly bunch to noob ideas ;). Hey i got a better idea, lets go to the IRS and see if we can persuade them to stop taxing us... That's where discussions about the documentation should be held. haha - I'm just curious to see how long it will for them to shut the discussion down. Yea, probably not long at all, of course not before the troll calling, bulling, defamation of character, etc, has lost it's fun. Before you do that, you should clearly work out in your own mind how you think things need to improve. It's not good enough just saying this or that is bad without having specific ideas on what needs to change. see links that xah posted, and there is more he did not post. Good luck fellow sinner and blasphemer... How dare you suggest that things could be improved... how dare YOU suggest they NOT be improved!!! -- http://mail.python.org/mailman/listinfo/python-list
Re: Social problems of Python doc [was Re: Python docs disappointing]
Since you're talking about documentation, which is a part of python, don't you think you should be discussing it on python-dev ? That's where discussions about the documentation should be held. haha - I'm just curious to see how long it will for them to shut the discussion down. Before you do that, you should clearly work out in your own mind how you think things need to improve. It's not good enough just saying this or that is bad without having specific ideas on what needs to change. Good luck fellow sinner and blasphemer... How dare you suggest that things could be improved... On Sun, 9 Aug 2009 20:04:43 -0700 (PDT), Xah Lee xah...@gmail.com wrote: The prob with python docs is with the python priests. there are frequent posts about python doc's poor quality, and some efforts to improve the doc (such as wiki or seggestions), about few times a year (in so much as i've seen), the typical response is pissing fight, with python priests to tell them not to start another wiki, or “you should apply in our church first and formulate a PEP proposal first or kindly donate or otherwise fuckoff”, and so on. i've wrote several articles about this issue, total time spend on this is probably more than 2 months full-time work. See: • Python Documentation Problems http://xahlee.org/perl-python/python_doc_index.html just about each article above generates a thread of flames. I also have re-wrote the entire python regex doc in 2005: • Pyhton Regex Documentation: String Pattern Matching http://xahlee.org/perl-python/python_re-write/lib/module-re.html there are some positive reviews, but most are drawn out by nay-sayers. I often receive thank you emails for 2 particular articles, which are most frequently google searched as indicated by my weblog: • Python Doc Problem Example: gzip http://xahlee.org/perl-python/python_doc_gzip.html • Python Doc Problem Example: sort() http://xahlee.org/perl-python/python_doc_sort.html • Sorting in Python and Perl http://xahlee.org/perl-python/sort_list.html See also: • Language, Purity, Cult, and Deception http://xahlee.org/UnixResource_dir/writ/lang_purity_cult_deception.html Xah ∑ http://xahlee.org/ ☄ On Jul 31, 1:10 pm, kj no.em...@please.post wrote: I'm pretty new to Python, and I like a lot overall, but I find the documentation for Python rather poor, overall. I'm sure that Python experts don't have this problem: they have internalized some good ways to access the documentation, are productive with it, and therefore have lost the ability to see why the Python documentations is deficient for beginners. This explains why a suboptimal situation can persist like this: those who are most able fix it are also the least able to perceive it. I've heard similar complaints from other experienced programmers who are trying out Python for the first time: poor documentation. Here is an *entirely typical* example: on some Unix, try % pydoc urllib The displayed documentation mention the optional parameter data in practically every function listed (a few dozen of them). This parameter is not documented *anywhere* on that page. All that we are told is that its default value is always None. I'm sure that I can find a full description of this parameter if I fire up Google, and search online. In fact, more likely than not, I'll find far more documentation than I want. But my point is that a programmer should not need to do this. The full documentation should be readily accessible directly through a few keystrokes. I would love to know how experienced Python programmers quickly zero in on the Python documentation they need. TIA! kynn -- http://mail.python.org/mailman/listinfo/python-list
