From: Ryan Davis <ryand-ruby@...>
Date: 2011-08-03T05:28:35+09:00
Subject: Re: Documentation Improvement Proposal


On Aug 2, 2011, at 12:46 , Steve Klabnik wrote:

> I am not ultra-familiar, I just know that it exists, that they care
> about it, and that often, I hear "Python is better than Ruby because
> Ruby's documentation sucks and Python's is great." And I think that's
> pretty much true. I'd most certainly be willing to investigate their
> process, ping some people to ask them about it, etc, if that'll help
> move things forward.

I suspect that they have a better time at it because they're not also dealing with a language barrier for the stuff that exists. Now that Eric has taken the baton, commits are being made much much faster and I suspect will accelerate slowly over time (the better the doco is, the easier it is to read, the easier it is to improve).

I would love to know more about the pydoco group and see if we can't adopt any of their practices where it makes sense.

>> Since I'm more of a person to do things than make them pretty I'd appreciate help in such matters.
>> Yes, please provide feedback.
> 
> The biggest problem that I have with Ruby's documentation is that it's
> all just API docs. That's fine, but there needs to be guides-style
> documentation, too. I get newbies that finish the paltry lessons I've
> finished for Hackety Hack asking me what next to read all the time,
> and I have to point them at the Pickaxe or the Poignant Guide. The
> fact that I can't simply point them at some sort of officialish
> documentation is pretty poor.

I dunno about now, but back when I was doing perl, python, java, etc... it was _all_ API doco and the rest was books. I'm not using that as an excuse. I'm just trying to set the bar at a rational level.

> I'm making a note to send you an email about this sometime this week
> or early next. I was going to anyway, but since this has come up, I'll
> make sure to, now.

appreciated.