OpenSource documentation problems

[Michael Sparks]

Hi Paul,


Paul Rubin wrote:
> Michael Sparks <ms at cerenity.org> writes:
[[[ some random stuff, /intended/ at supporting people who have contributed
  docs, rather than saying people who offer constructive suggestions are
  bad. Possibly badly written. ]]]
> I've submitted a number of doc bugs to sourceforge and the ones that
> are simple errors and omissions do get fixed.  

Cool. 

> However, your 
> suggestion doesn't constitute good Python advocacy, if that's what you
> were attempting.  

Nope. I rarely attempt advocacy because I'd suck at it if I tried (worse
than my docs :), and also I'm not a fan of advocacy anyway - I prefer to
make up my own mind rather than be told. 

> When I use a tool like Python, I like to think I'm 
> working on one project at a time, that project being whatever I'm
> trying to develop.  

> Telling me that whenever I use Python, I should 
> really consider myself to be working on two projects at once

I didn't mean it that way (I probably put it over the wrong way). What I did
mean is that when someone in here says "someone here should make the docs
better", is naturally including themselves in the set of people who can
write docs. If they then attack people who /can/ write docs they're
attacking themselves. 

Stating that something needs writing or updating I'd agree is good. People
whinging because no-one has written it, or constantly dissing docs without
helping improve them strikes me as unfair.

To my mind yourself, Bryan, Steve, Terry and others in the thread contribute
amazingly (and I wish I had more time to do so), by simply being nice and
helpful in *here*.

>> [ O'Reilly, and friends, books as a docs for open source ]
> 
> If those docs aren't free to redistribute, then that's not an
> open-source solution at all; if anything, it's an anti-solution, since
> it decreases the motivation to write good free docs.

OK, it's not the best solution in the world I'll agree, but my point was in
general very few people like writing docs even when paid, let alone when
not. As a result it's not that suprising IMO that if paid you end up with
more docs. 

> Even weirder is the amount of gratis (free as in beer) but unfree (as
> in freedom) docs out there for Python.  

I'm not aware of those, so I don't feel able to comment sensibly.

>> The best way to repay those who have spent the time writing what can
>> be viewed as a first draft is to provide corrections. If you
>> (generic, not just you personally) don't have the time, effort,
>> inclination or effort to summarise and feedback a documentation
>> patch *why should anyone else* ?
> 
> I usually do report doc bugs, but my frustration (and I think Bryan's)
> is that there are so many bugs in the first place.  It means that the
> authors are not applying high enough quality standards to their own
> work before releasing it.  That applies to Python's code as well as
> its docs.  It's not crap,

Or maybe they're just doing their best? It might seem silly but when I do
write docs, personally it takes me around 4-10 times longer to write the
same number of lines as documentation than as code, whilst trying to
maintain a similar quality. I think thats on a good day.

> but it's not at the level that those of us 
> from the non-Windows world like to (realistically or otherwise) expect.

FWIW, I'm not part of the windows crowd. Ceased using windows regularly
around Windows 3.1, and have periodically gone back (95, 98, ME, 2000, XP)
to see whether it's improved, and come to the conclusion for me it's a
downgrade in the way I work. It is sometimes useful for playing DVDs on
long journeys though since the power management works better IME.

[ specific example of bad or missing docs snipped ]

I agree there's always valid criticisms.

> I think there is an attitude problem in the central Python development
> community, which is to expect external volunteers to do stuff with no
> cajoling and no guidance.  That just doesn't work very well.  

I have no idea what to do about that. Giving T-Shirts to people who write a
decent tutorial that covers an entire library module? (Semi-serious if
there's a way of making that work)

> I was the first FSF staff programmer on the GNU project and we spent a LOT
> of our time coordinating volunteers and maintaining lists of tasks to
> recruit people to do, and generally trying to make stuff happen
> according to what we saw as the project's priorities, as opposed to
> simply passively waiting for code and doc contributions to come to us
> fully done.  We also saw doing gap-filling and grunt-work that didn't
> excite volunteers to be an important part of our purpose as paid
> staff: if somebody had to do it and no one volunteered, then the
> somebody was us.

This might sound really dumb, but I'd be genuinely interested to hear more
about how you organised this, how you managed to motivate people to do
these things, what "rewards" the people got for doing this. (Working on the
assumption that rewards range from simple thanks upwards!)

>> it's ironic though because they're criticising themselves. After all
>> they understand how the docs can be better and the docs are
>> shared. Unless they contribute back they're actually attacking
>> themselves as much as the person who "wastes" their time writing
>> "worthless" docs.
> 
> Calling the Python docs "worthless" is false and unconstructive;

That was really my point as well, FWIW.

> saying that the docs have shortcomings in part because the Python
[ ... snip stuff I generally agree with ... ]
> important as code.

>> (Again, not specifically aimed at you, but unless you've actually
>> contributed back the results of your findings, you have to realise that
>> any reasons or excuses that apply to you may also apply to
>> anyone/everyone in the group and it's therefore suprising we have any
>> docs ! :-)
> 
> Python has been shipping Tkinter as part of its stdlib for something
> like ten years now without any docs.  That doesn't take much of a
> "finding" to notice.  And it's not simply a gap needing filling.  That
> such a huge hole could exist for that long shows a systemic problem.

Maybe there is a systemic problem. Do you have a suggestion as to how to
correct it? (The reason I ask is in the hope that either I'd have time to
help resolve it if it exists, or someone else might. If I've missed a
suggestion for how to correct it elsewhere, my apologies :-/ , just tell me
to google :-)

Best Regards,


Michael.