OpenSource documentation problems

[Rocco Moretti]

Steve Holden wrote:

> Every page of the docs links to "About this document", which contains 
> the following: """If you are able to provide suggested text, either to 
> replace existing incorrect or unclear material, or additional text to 
> supplement what's already available, we'd appreciate the contribution. 
> There's no need to worry about text markup; our documentation team will 
> gladly take care of that."""

There is just one giant roadblock to that suggestion - Sourceforge 
requires a login to post bugs/patches.

It doesn't seem like much, but as Paul Rubin mentioned, most people who 
find bugs/unclear passages in the docs aren't scanning the docs 
explicitly to edit them - they've uncovered the bug after working on 
some other project, and likely only after banging their head against the 
wall a few times trying to get it to work. If they have to go through 
the song and dance of signing up for another website to report the 
problem, they might just say "forget it."

Sure, it's not hard to sign up for Sourceforge, but even a little 
barrier can stop you from contributing if you're not enthusiastic about 
it in the first place.

Something a simple as allowing doc bugs to be submitted from a webform 
w/o login would reduce the barrier to contribute. - Increasing the size 
of the "About" text wouldn't hurt either. (To be honest, I've never 
noticed that text before, and it never occurred to me look at the 
"About" page for information on error reports.)

That said, I think the Python manuals are great. But saying that they 
are perfect, or that the editing process couldn't be improved is just 
deluding yourself.