Doc suggestions

[rurpy at yahoo.com]

"Terry Reedy" wrote:
> <rurpy at yahoo.com> 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.