[Python-Dev] status of development documentation

Thu Dec 22 09:55:30 CET 2005

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>