OpenSource documentation problems

[Paul Rubin]

Michael Sparks <ms at cerenity.org> writes:
> > A plausible theory. I have some possibly-illustrative examples
> > of what I ran into within the last few weeks.
> 
> <hypothetical> Did you take what you learnt, and use that to create better
> documentation to be posted on python's SF project as a patch?
> </hypothetical> 

I've submitted a number of doc bugs to sourceforge and the ones that
are simple errors and omissions do get fixed.  However, your
suggestion doesn't constitute good Python advocacy, if that's what you
were attempting.  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 (doing my
own project, plus helping develop Python or its docs) makes it sound
like you're recommending a tool that has no intention of ever really
leaving beta test.  

Python's docs are nowhere near the worst I've seen, but I have to say
that various other free software projects manage to hold to higher
standards for both code and documentation than Python seems to deem
worth bothering with.  I have a theory about why this might be, which
starts with W and comes from Redmond.  But I'll skip that.

> Ironically though I do think the problem of documentation has been
> half solved in the open source world, and it really boils down (IMO)
> to companies like O'Reilly who appear to try and target popular
> not-best-documented open source projects and provide the
> motivation that results in good documentation.

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.

Even weirder is the amount of gratis (free as in beer) but unfree (as
in freedom) docs out there for Python.  I'm thinking of docs like like
John Shipman's Tkinter reference manual from nmt.edu, which while not
perfect is extremely useful.  There's no money being collected for it,
and thus no profit motive for not explicitly licensing it under terms
that allow including it in Python and other free software distros, and
yet this isn't being done.  Somewhat more understandable, but also
counterproductive to Python as a FOSS project, is semi-gratis stuff
like the ASPN docs.

> 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, but it's not at the level that those of us
from the non-Windows world like to (realistically or otherwise) expect.

> When people complain /in here/ about the documentation not being
> perfect for python I personally find it sad and ironic. It's sad
> because it says to the person who spent their time (when they could
> be doing something else) that they wasted it, the docs are worthless
> etc - when they clearly *haven't* wasted their time and the docs are
> worthwhile.

I don't understand what you mean by that.  For example, there are
practically no useful Tkinter docs in the Python distro.  That is a
legitimate gripe against Python.  There's a workaround in the form of
some docs available from external sources (above).

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

The FSF's emphasis has changed somewhat since then, but my (admittedly
biased) opinion remains that the quality of the work we did in those
days, both in code and docs, was better than what I see coming out of
Python.org today.  We didn't have more talent or resources or anything
like that.  We just had a different attitude, of trying to do stuff
right whenever we could, and to provide a driving force rather than
waiting for stuff to happen without our initiative.  (It helped that
RMS was very intolerant of sloppiness, and he raised everyone's
standards).

> 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;
saying that the docs have shortcomings in part because the Python
project itself places too little priority on doc quality is perfectly
legitimate.  Python's core developers are in a leadership position for
Python whether they like it or not; and users and volunteers absorb
the attitudes of the leaders.  The PSF and the FSF both sometimes fund
people to do coding projects.  Why does the PSF (apparently) not fund
anyone to do doc projects, like the FSF does?  I would say this shows
the PSF's priorities are screwed up.  Documentation is every bit as
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.