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>
_______________________________________________
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
