"Terry Reedy" wrote: > <[EMAIL PROTECTED]> wrote in message > > "Terry Reedy" wrote:
> Yes, there have been claims that doc patches have to be in Latex or are > otherwise not welcome. But these mostly (all?) have lacked relevant > concrete data, which would be actual responses to actual submissions to the > Python SourceForge change trackers. Yes, I have seen here many times, and read in the doc footnotes, that any form of doc patches are acceptable. I never thought or claimed otherwise. >... > Some time ago, Alex Martelli submitted several style change suggestions for > at least one of the docs. As I remember, at least most of them were > accepted. In any case, all were considered. And there have since been > other changes that I have been involved with that were arguably style > upgrades rather than corrections. Given Alex Martelli's level of competence that is neither surprising or representative. > A few organizational changes might be considered, especially if accompanied > by an offer to make at least a prototype, but someone with fundamentally > different ideas should write their own doc under their own name. That puts a pretty high bar in place for the Language Reference which has no hope if becoming good without major organizational changes. >... > Suggestion: You could submit the one improved sentence you previously > suggested. But the overhead of any change is a bit high for just that. So > gather at least a few suggestions, put them in order, include section > number and identifier for each, and cut-and-paste urls from current docs at > python.org. What I am questioning is why those barriers are so high. Why does fixing a even a clear, obvious, fault in the documentation require someone to log in to sourceforge, create a bug or patch entry, have someone else review it, comment it, change a half dozen words in the source, close it... Why can't the folks doing the docs be more proactive? > Offer: If you submit your 'text patch' to SourceForge and let me know, I > will review it right away. [...] I appreciate the offer, but special treatment for someone who raises a public stink is not going to fix the underlying problem, is it? Here is a 30000' view. I posted about a clear (admittedly very minor) doc problem 8 days ago. Since then there have been 30+ postings in this thread. Insults and bad feelings have flown. Two people setup wikis and uploaded the tutorial. I don't know how many people have visited or made changes. After all that I look at the current 2.5 docs, and what do I see? The same, trivial, problem is still there. Am I the only one who sees something wrong with this picture? That change was simple and uncontroversial enough so that someone should have simply done it. Why is a formal change procedure needed for this level of change? My guess is the people taking care of the docs are Python developers whose main interest is Python but who also generously volunteer to handle docs issues. And probably most don't even read c.l.p. Is that close? Around christmas time there was a long discussion here and on the python doc mailing list about how to fix things. I was gone at the time but I read a lot of it when I returned. One thing stuck out like a sore thumb. There were hundreds of messages about redit vs latex, html vs xml, toolchains, wikis, patch managers, software packages. There were almost no messages about *WRITING* and *EDITING*. Part of the problem is undeniably the need for a good infrastructure. But... The other half, which has been nearly unaddressed as far as I can tell, is PEOPLE! The docs problem is a people problem, and won't be solved by technology. (Unless someone here is very good with AI :-) Here is how I would arrange things if I could... =================================== A psf project or sig or some other discrete unit chartered to work on the docs. Active, encouraging, solicitation of people with good (natural) language skills to participate. Detailed written style guidelines and document scopes so that everyone is, if not on, at least near the same page. Division of volunteers into (roughly) Czar or small committee, Editors, Writers, Everyone else. Top level czar or small committee sets overall doc policy and standards, resolves differences of opinion. Editors responsible for ensuring the docs have consistent style and appropriate content/level. (By rewriting and editing more than by rejecting submissions.) Writers who create new material and correct/improve existing material. Everyone else who will be encouraged to report doc errors, unclarities, suggest improvements, etc. Specific areas of interest assigned publicly to specific writers/editors (voluntarily of course), both to provide them with public recognition and as a minor incentive for them to get something done. A definition of what constitutes an minor change and the ability of volunteers to make such changes unilaterally. Facilitation of a fast-path communication channel between the person maintaining the docs for a package, and the developers/maintainers of that package, so questions can get asked and answered quickly. Use of a wiki or similar for: - Collaborative work among the writer and editors - Collection of comments and suggestions from users about both the released python docs, and the in-progress fixes/improvements (this part is what FL has prototyped). Foster a nurturing environment where people are not afraid to make changes. ================================ This may be too top heavy for some people. But the bottom line is that an effort has to be made to get PEOPLE involved in WRITING and EDITING. I personally think it will require more than waiting for a wiki to self-organise. -- http://mail.python.org/mailman/listinfo/python-list
