Rocco Moretti wrote: > Steve Holden wrote: > > >>Every page of the docs links to "About this document", which contains >>the following: """If you are able to provide suggested text, either to >>replace existing incorrect or unclear material, or additional text to >>supplement what's already available, we'd appreciate the contribution. >>There's no need to worry about text markup; our documentation team will >>gladly take care of that.""" > > > There is just one giant roadblock to that suggestion - Sourceforge > requires a login to post bugs/patches. > Well OK, I have to descend to observations based on personal experience here, but way back when I was a Python noob and I had a suggestion about how the docs might be [slightly] improved I just actioned the first sentence in the paragraph from which I extracted my previous quote. That reads:
"""General comments and questions regarding this document should be sent by email to [EMAIL PROTECTED]""" Shortly after emailing [EMAIL PROTECTED] I had an extremely polite reply from Fred Drake thanking me for the suggestion and agreeing to make the suggested change. I don't know what stops people from jumping in with both feet, but it certainly isn't the unapproachability of the documentation team - all one of him. > It doesn't seem like much, but as Paul Rubin mentioned, most people who > find bugs/unclear passages in the docs aren't scanning the docs > explicitly to edit them - they've uncovered the bug after working on > some other project, and likely only after banging their head against the > wall a few times trying to get it to work. If they have to go through > the song and dance of signing up for another website to report the > problem, they might just say "forget it." > I can understand people's recitence, so *maybe* it would be better if the request for contributions clearly stated that amendments in plain text would be welcomed. Having done a bit of writing myself I am pretty sure that Fred would have to spend far less time deciding how to mark up some intelligent reader's plain text revisions than he would having to express the same thoughts coherently himself. The developers have full-time jobs as well, so everything we can do to help them (I have had sourceforge commit rights in the past but I recently gave them up and never really regarded myself as a "developer") will give them more time to focus on improving the language. > Sure, it's not hard to sign up for Sourceforge, but even a little > barrier can stop you from contributing if you're not enthusiastic about > it in the first place. > I refuse to believe that it's harder to sign up for Sourceforge than it is to post a bitching comment on c.l.py. This is not to say that it couldn't be easier to contribute change suggestions to the docs, but I still believe that most of the bitching and moaning comes from people who'd rather bitch and moan than roll their sleeves up. Otherwise it wouldn't have taken me three years to offload the PyCon chair (thanks, Andrew :-) > Something a simple as allowing doc bugs to be submitted from a webform > w/o login would reduce the barrier to contribute. - Increasing the size > of the "About" text wouldn't hurt either. (To be honest, I've never > noticed that text before, and it never occurred to me look at the > "About" page for information on error reports.) > So, probably the best outcome of this current dialogue would be a change to the bottom-of-page comment so instead of saying """Release 2.4, documentation updated on 29 November 2004. See About this document... for information on suggesting changes. """ it said """Release 2.4, documentation updated on 29 November 2004. See About this document... for information on suggesting changes, or mail your suggestions to [EMAIL PROTECTED]""" > That said, I think the Python manuals are great. But saying that they > are perfect, or that the editing process couldn't be improved is just > deluding yourself. Well I make a habit of deluding myself. The world is a beautiful place, every reader of c.l.py has my welfare at heart, and even Perl programmers will learn better in time; and all contributors who debate this topic will be happy to volunteer to help process the additional mails that would result from the suggested change. I'll just point to my book and my three years as PyCon chair as an excuse for not getting off my butt in this particular instance :-) with-a-sense-of-community-ly y'rs - steve PS Anyone who contributes will also have the delight of being able to point to their name at http://docs.python.org/acks.html. I was surprised to find I made it on that list just for a suggestion, way before I took on the task of documenting asyncore and asynchat. -- Steve Holden +44 150 684 7255 +1 800 494 3119 Holden Web LLC http://www.holdenweb.com/ -- http://mail.python.org/mailman/listinfo/python-list
