Doc suggestions

[Terry Reedy]

<rurpy at yahoo.com> wrote in message
news:1143762250.537475.115420 at t31g2000cwb.googlegroups.com...
> "Terry Reedy" wrote:
> Not sure how premature it is.  I've been reading
> c.l.p. on and off for nearly a year.

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.

There have also been fact-based postings at least partly refuting such 
claims, including some by me.

>> >  I gather corrections of factual
>> > errors are welcome, but stylistic, or organizational
>> > ones are not.

I would not be surprised if the volunteer doc editors see corrections and 
the writing of missing docs as higher priority than sylistic upgrades, but 
that is different from 'not welcome'.

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.

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.

>> If you wish to become a volunteer Python improver, let me know either
>> here or privately and I will respond with a suggestion and an offer.
>
> Yes, please do.

Frederik has one idea.  Here is what I was going to say, and will anyway.

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.

Offer: If you submit your 'text patch' to SourceForge and let me know, I 
will review it right away.  If you prefer, post or email to me and I will 
'pre' review it before submission.  You can collect ideas from others if 
you want; I only care about formating that make the proposed change sites 
and contexts easy to find.

Terry Jan Reedy