[Python-Dev] Re: Stability and change

[François Pinard]

[Guido van Rossum]

> Have you read the library manual recently?

No.  I read manuals a few times quite carefully, but now am only using
them as references.  As a user, I cannot really afford reading everything
at each release.

> We are very careful in adding notes about which version added a particular
> feature or even detail.  So I think there is no reason to complain about
> this preemptively unless your *own* experience indicates there's a lack
> of documentation.

Checking random sections of the library reference for actual needs, I
remember having had to cross-check with previous printing of the same to make
sure that the code I was writing could be ported to other machines running
older Python versions.  I would probably not have done this if I stumbled
on that information in the first place, so it may lack here or there.

It is very nice that you are careful about adding notes as you explain
above, thanks for all of us.  If I meet other unclear cases, I'll try
reporting them precisely in the future (yet I'm surprised by the amount
of email which is sometimes needed to get a little point through.)

My own experience has no frustration, because I took the time to check.
I only guess that other's experience may yield frustration for them,
witnessing the reluctance or anger of some of my co-workers to any kind
of change.  Surely, I do not feel real problems myself.  Maybe I should
shut up.  I only thought useful, at least a bit, that I try to explain what
I see around, because I know my co-workers are not going to step in the
public discussion arena (they also have to go over the English barrier),
and presume most users are just silent alike.

> Hm.  People who don't read the detailed documents shouldn't expect to
> rely on details.

You know, everything is a detail of some sort, and at least for newcomers,
the language and the library are mere accumulation of details.  Users just
cannot program without relying on these.  One needs a lot of perspective
for sorting out the relative importance of various specifications.  So,
in your argument above (which I find a bit harsh), it might not be very
realistic expecting that people read everything in every release.  It is
reasonable to expect users to read everything once, however -- and users
may then have to wave between sites, distributions, and Python releases.

If you try putting perspective and historical notes in the documentation,
this is very good, and I guess it will be helpful for many people.

-- 
François Pinard   http://www.iro.umontreal.ca/~pinard