Michael Sparks <[EMAIL PROTECTED]> writes: > > A plausible theory. I have some possibly-illustrative examples > > of what I ran into within the last few weeks. > > <hypothetical> Did you take what you learnt, and use that to create better > documentation to be posted on python's SF project as a patch? > </hypothetical>
I've submitted a number of doc bugs to sourceforge and the ones that are simple errors and omissions do get fixed. However, your suggestion doesn't constitute good Python advocacy, if that's what you were attempting. When I use a tool like Python, I like to think I'm working on one project at a time, that project being whatever I'm trying to develop. Telling me that whenever I use Python, I should really consider myself to be working on two projects at once (doing my own project, plus helping develop Python or its docs) makes it sound like you're recommending a tool that has no intention of ever really leaving beta test. Python's docs are nowhere near the worst I've seen, but I have to say that various other free software projects manage to hold to higher standards for both code and documentation than Python seems to deem worth bothering with. I have a theory about why this might be, which starts with W and comes from Redmond. But I'll skip that. > Ironically though I do think the problem of documentation has been > half solved in the open source world, and it really boils down (IMO) > to companies like O'Reilly who appear to try and target popular > not-best-documented open source projects and provide the > motivation that results in good documentation. If those docs aren't free to redistribute, then that's not an open-source solution at all; if anything, it's an anti-solution, since it decreases the motivation to write good free docs. Even weirder is the amount of gratis (free as in beer) but unfree (as in freedom) docs out there for Python. I'm thinking of docs like like John Shipman's Tkinter reference manual from nmt.edu, which while not perfect is extremely useful. There's no money being collected for it, and thus no profit motive for not explicitly licensing it under terms that allow including it in Python and other free software distros, and yet this isn't being done. Somewhat more understandable, but also counterproductive to Python as a FOSS project, is semi-gratis stuff like the ASPN docs. > The best way to repay those who have spent the time writing what can > be viewed as a first draft is to provide corrections. If you > (generic, not just you personally) don't have the time, effort, > inclination or effort to summarise and feedback a documentation > patch *why should anyone else* ? I usually do report doc bugs, but my frustration (and I think Bryan's) is that there are so many bugs in the first place. It means that the authors are not applying high enough quality standards to their own work before releasing it. That applies to Python's code as well as its docs. It's not crap, but it's not at the level that those of us from the non-Windows world like to (realistically or otherwise) expect. > When people complain /in here/ about the documentation not being > perfect for python I personally find it sad and ironic. It's sad > because it says to the person who spent their time (when they could > be doing something else) that they wasted it, the docs are worthless > etc - when they clearly *haven't* wasted their time and the docs are > worthwhile. I don't understand what you mean by that. For example, there are practically no useful Tkinter docs in the Python distro. That is a legitimate gripe against Python. There's a workaround in the form of some docs available from external sources (above). I think there is an attitude problem in the central Python development community, which is to expect external volunteers to do stuff with no cajoling and no guidance. That just doesn't work very well. I was the first FSF staff programmer on the GNU project and we spent a LOT of our time coordinating volunteers and maintaining lists of tasks to recruit people to do, and generally trying to make stuff happen according to what we saw as the project's priorities, as opposed to simply passively waiting for code and doc contributions to come to us fully done. We also saw doing gap-filling and grunt-work that didn't excite volunteers to be an important part of our purpose as paid staff: if somebody had to do it and no one volunteered, then the somebody was us. The FSF's emphasis has changed somewhat since then, but my (admittedly biased) opinion remains that the quality of the work we did in those days, both in code and docs, was better than what I see coming out of Python.org today. We didn't have more talent or resources or anything like that. We just had a different attitude, of trying to do stuff right whenever we could, and to provide a driving force rather than waiting for stuff to happen without our initiative. (It helped that RMS was very intolerant of sloppiness, and he raised everyone's standards). > it's ironic though because they're criticising themselves. After all > they understand how the docs can be better and the docs are > shared. Unless they contribute back they're actually attacking > themselves as much as the person who "wastes" their time writing > "worthless" docs. Calling the Python docs "worthless" is false and unconstructive; saying that the docs have shortcomings in part because the Python project itself places too little priority on doc quality is perfectly legitimate. Python's core developers are in a leadership position for Python whether they like it or not; and users and volunteers absorb the attitudes of the leaders. The PSF and the FSF both sometimes fund people to do coding projects. Why does the PSF (apparently) not fund anyone to do doc projects, like the FSF does? I would say this shows the PSF's priorities are screwed up. Documentation is every bit as important as code. > (Again, not specifically aimed at you, but unless you've actually > contributed back the results of your findings, you have to realise that any > reasons or excuses that apply to you may also apply to anyone/everyone in > the group and it's therefore suprising we have any docs ! :-) Python has been shipping Tkinter as part of its stdlib for something like ten years now without any docs. That doesn't take much of a "finding" to notice. And it's not simply a gap needing filling. That such a huge hole could exist for that long shows a systemic problem. -- http://mail.python.org/mailman/listinfo/python-list
