[Python-Dev] The docs, reloaded

[Jim Jewett]

Martin v. Löwis schrieb:

> That docutils happens to be written in Python should make little
> difference - it's *not* part of the Python language project,
> and is just a tool for us, very much like latex and latex2html.

Not entirely.  When I first started looking at python, I read a lot of
documentation.  Now I don't read it so much; the time when I could
easily suggest doc changes without explicitly setting time aside has
passed.

At that time, the barriers to submitting were fairly large; these are
the ones I remember:

(1)  Not realizing that I *could* submit changes, and they would be welcome.
(2)  Not understanding it well enough to document it correctly.
(3)  Not having easy access to the source -- I didn't want to to
retype it, or to edit html only to find out it was maintained in some
other format.  Even once I found the cvs repository, the docs weren't
in the main area.
(4)  Not having an easy way to submit the changes quickly.
(5)  Wanting to check my work, in case I was wrong.

I have no idea how to fix (1) and (2).

Putting them on a wiki improves the situation with (3) and (4).

(5) is at least helped by keeping the formatting requirements as
simple as possible (not sure if ReST does this or not) and by letting
me verify them before I submit.

Getting docutils is already a barrier; I would like to see a stdlib
module (not script hidden off to the side) for verification and
conversion.  I don't think I installed docutils myself until I started
to write a PEP.  But once I did download and install and figure out
how to call it ... at least it generally worked, and ran with
something (python) I was already using.

Getting a 3rd party tool that ends up requiring fourth party tools
(such as LaTex, but then I need to a viewer, or the old toolchain that
required me to install Perl) ... took longer than my attention span.
This was despite the fact that I had already used all the needed tools
in previous years; they just weren't installed on the machines I had
at the time ... and installing them on windows was something that
would *probably* work *eventually*.  If I had been new to programming,
it would have been even more intimidating.

-jJ