[Python-Dev] status of development documentation

[Fredrik Lundh]

Fred L. Drake, Jr. wrote:

>  > I'm not convinced it's the toolchain though.  People hate writing
>  > documentation.  Getting people to contribute documentation is worse than
>  > pulling teeth.
>
> I don't think it's the toolchain either.  While most people don't have it,
> it's easier and easier to get a decent toolchain on Linux; TeX just isn't as
> hard to have around as it used to be.
>
> I suspect that part of the problem is that there's no need to write
> documentation to scratch itches: once you know what to write, your itch has
> been scratched (you're already able to make the changes needed to your own
> code);

If an ordinary user finds a minor issue, a type, or an error in the documentation,
the current user workflow is:

    1) (optionally) cut and paste the text to an editor, edit, and save to disk
    2) go to the sourceforge site, and locate the python project
    3) (optionally) sign up for a sourceforge account
    4) log in to your sourceforge account
    5) open a new bug or patch issue, and attach your suggestion
    6) wait 3-6 months for someone to pick up your patch, and for the
       next documentation release to appear on the site

If the documentation had been placed in a wiki:

    1) click edit, fix the text, and click save

If the documentation had been connected to a discussion board (PHP-style)

    1) click post new message, write a note, and click save

With a "user edit" mechanism (connected either to a mailing list, or roundup),
and documentation regularily updated from the trunk, the workflow is:

    1) click edit, update the text, preview, and click submit
    2) wait a few days for someone to pick up your patch, and a day for
       the documentation to be regenerated.

On the maintainer side, wikis and discussion boards require regular monitoring
to avoid abuse.  A user edit mechanism requires about the same work as today
(except that an edit mechanism with preview tends to result in patches that are
a lot more "ready for use", in my experience).

> nobody is relying on the updated documentation to be released to use what
> they figured out, even if they noted that the documentation was lacking to
> start with.

I know what you mean here, but read the wrong way, that sentence is so com-
pletely off the track so I don't know where to start.  People love to contribute
bits of information, especially when they get feedback (this is of course what
powers places like python-list, not to mention the entire blog universe).  Let's
use this human feature to our advantage.

</F>