[Python-Dev] introducing the experimental pyref wiki

["Martin v. Löwis"]

Guido van Rossum wrote:
> Agreed. Is it too late to also attempt to bring Doc/ref/*.tex
> completely up to date and remove confusing language from it? Ideally
> that's the authoritative Language Reference -- admittedly it's been
> horribly out of date but needn't stay so forever.

It's never too late to update the specification. I really think there
should be a specification, and I really think it should be as precise
as possible - where "possible" takes both of these into account:
- it may get out of date due to lack of contributors. This is free
  software, and you don't always get what you want unless you do
  it yourself (and even then, sometimes not).
- it might be deliberately vague to allow for different implementation
  strategies. Ideally, it would be precise in pointing out where it
  is deliberately vague.

So I think the PEPs all should be merged into the documentation,
at least their specification parts (rationale, history, examples
might stay in the PEPs).

To some degree, delivery of documentation can be enforced by making
acceptance of the PEP conditional upon creation of documentation
patches. Once the feature is committed, we can only hope for (other)
volunteers to provide the documentation, or keep nagging the author
of the code to produce it.

Regards,
Martin