[Python-Dev] status of development documentation (original) (raw)

Fredrik Lundh fredrik at pythonware.com
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.

More information about the Python-Dev mailing list