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

Michael Hudson mwh at python.net
Thu Dec 22 12:51:40 CET 2005

"Fredrik Lundh" <fredrik at pythonware.com> writes:

Checked the python-list archives lately? If you google c.l.python for the word "documentation", you'll find recent megathreads with subjects like "bitching about the documentation", "opensource documentation problems" and "python documentation should be better" among the top hits. But if you check the bug and patch trackers, you don't find many contributions. Something's definitely broken.

Hmm, it's this discussion again! Let me make my point again!

Writing good documentation is hard.

And sometimes the problem is that the document isn't really structured right, or it has been hastily updated to cover too many changes that it's a dogs breakfast, or some other 'global' problem and these really take time to fix. I really, really don't think the formatting tools make that much difference in the grand scheme of things. I think streamlining the process of getting a patch in would help a lot more (and not just for the documentation, obviously) but still not that much.

Cheers, mwh (another one in the 'hates editing HTML' camp, if anyone's counting)

-- The ability to quote is a serviceable substitute for wit. -- W. Somerset Maugham

More information about the Python-Dev mailing list