OpenSource documentation problems

[Terry Hancock]

On Thursday 01 September 2005 04:03 am, Fredrik Lundh wrote:
> Steve Holden wrote:
> > I agree that maintaining documentation is a generic problem of the open
> > source world, but it's a sad fact of life that generally people are
> > better-motivated to complain about documentation (and almost everything
> > else) than to help improve it.
> 
> another problem is that to be able to do really good work on the
> documentation, you need to know things well enough to "have the
> big picture".  and once you have that, you'll find that the docs aren't
> really as bad as you once thought they were.

Or "Once you understand the problem well enought to explain it to
someone, it suddenly seems a lot less urgent to do so."  That's kind
of a viscious circle, isn't it?

Honestly, I wouldn't mind helping out with documentation myself, as
I'm pretty confident I could do fairly good work (though I doubt I
would ever please XL), but I just haven't found anything that bothered
me about Python's existing documentation.  Maybe I should look harder.

I do notice that we seem to have "learning styles" issues. The one
thing I've gathered from Xah Lee's execrable posts is that he learns
exclusively by studying examples, and gets nothing from descriptive
text. I'm almost exactly the opposite -- when I go to the documentation,
I'm looking for "the big picture" as you say. 

I have loads of example code to check for exact usage.  And after a
couple of weeks with Python, I stopped finding the library modules'
approach to things at all surprising. I generally could guess the
correct behavior and test it right away (I have been really surprised
at the number of times I just took a wild guess at what a method would
be called, and turned out to be right).

--
Terry Hancock ( hancock at anansispaceworks.com )
Anansi Spaceworks  http://www.anansispaceworks.com