OpenSource documentation problems

[Steve Holden]

Rocco Moretti wrote:
> 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.
> 
Well OK, I have to descend to observations based on personal experience 
here, but way back when I was a Python noob and I had a suggestion about 
how the docs might be [slightly] improved I just actioned the first 
sentence in the paragraph from which I extracted my previous quote. That 
reads:

"""General comments and questions regarding this document should be sent 
by email to docs at python.org."""

Shortly after emailing docs at python.org I had an extremely polite reply 
from Fred Drake thanking me for the suggestion and agreeing to make the 
suggested change.

I don't know what stops people from jumping in with both feet, but it 
certainly isn't the unapproachability of the documentation team - all 
one of him.

> 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."
> 
I can understand people's recitence, so *maybe* it would be better if 
the request for contributions clearly stated that amendments in plain 
text would be welcomed. Having done a bit of writing myself I am pretty 
sure that Fred would have to spend far less time deciding how to mark up 
some intelligent reader's plain text revisions than he would having to 
express the same thoughts coherently himself.

The developers have full-time jobs as well, so everything we can do to 
help them (I have had sourceforge commit rights in the past but I 
recently gave them up and never really regarded myself as a "developer") 
will give them more time to focus on improving the language.

> 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.
> 
I refuse to believe that it's harder to sign up for Sourceforge than it 
is to post a bitching comment on c.l.py. This is not to say that it 
couldn't be easier to contribute change suggestions to the docs, but I 
still believe that most of the bitching and moaning comes from people 
who'd rather bitch and moan than roll their sleeves up.

Otherwise it wouldn't have taken me three years to offload the PyCon 
chair (thanks, Andrew :-)

> 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.)
> 
So, probably the best outcome of this current dialogue would be a change 
to the bottom-of-page comment so instead of saying

"""Release 2.4, documentation updated on 29 November 2004.
See About this document... for information on suggesting changes. """

it said

"""Release 2.4, documentation updated on 29 November 2004.
See About this document... for information on suggesting changes, or 
mail your suggestions to docs at python.org"""

> 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.

Well I make a habit of deluding myself. The world is a beautiful place, 
every reader of c.l.py has my welfare at heart, and even Perl 
programmers will learn better in time; and all contributors who debate 
this topic will be happy to volunteer to help process the additional 
mails that would result from the suggested change.

I'll just point to my book and my three years as PyCon chair as an 
excuse for not getting off my butt in this particular instance :-)

with-a-sense-of-community-ly y'rs  - steve

PS Anyone who contributes will also have the delight of being able to 
point to their name at http://docs.python.org/acks.html. I was surprised 
to find I made it on that list just for a suggestion, way before I took 
on the task of documenting asyncore and asynchat.
-- 
Steve Holden       +44 150 684 7255  +1 800 494 3119
Holden Web LLC             http://www.holdenweb.com/