From: Xavier Noria Date: 2012-04-24T05:05:04+09:00 Subject: Re: To developers of Ruby: Feeble documentation - weakness of Ruby and the Ruby on Rails (2nd editio --e89a8f3b55885ba27f04be5e2746 Content-Type: text/plain; charset=UTF-8 On Mon, Apr 23, 2012 at 9:17 PM, Ryan Davis wrote: > Files: 144 > > > > Classes: 82 ( 28 undocumented) > > Modules: 90 ( 63 undocumented) > > Constants: 21 ( 20 undocumented) > > Attributes: 91 ( 84 undocumented) > > Methods: 822 (385 undocumented) > > > > Total: 1106 (580 undocumented) > > 47.56% documented > > That's the oldest and most established subproject in rails... meaning, it > has the least excuse to be less than 50% documented. > For some reason Gmail doesn't show me the origin of this thread. But that remark seems unfair to me. For starters, that statistic presented like that, cold, is not very meaningful. You'd need to add how many of the undocumented methods are public interface. Because we are talking about end users, to which internal documentation is not a concern. The documentation of Ruby on Rails has sure room for improvement, but you can't deny that since docrails was created the documentation is good. We get many documentation contribs via docrails, the guides, patches are not accepted without docs coverage. Could it be better? Always, but this project has documentation as a first class citizen nowadays. I wanted to state my point of view. I have interest zero on discussing whether a certain adjective is appropriate or not. Ruby has the same problem No, Ruby has a way worse problem. I am not complaining (in open source I very rarely complain), but to express my opinion about this, it is a matter of fact that Ruby documentation can't be compared with the quantity and quality of Rails documentation. --e89a8f3b55885ba27f04be5e2746 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable

On Mon, Apr 23, 2012 at 9:17 PM, Ryan Davis <ryand-ruby@zenspider.com> wrote:

> Files: =C2=A0 =C2=A0 =C2=A0 144
>
> Classes: =C2=A0 =C2=A0 =C2=A082 ( 28 undocumented)
> Modules: =C2=A0 =C2=A0 =C2=A090 ( 63 undocumented)
> Constants: =C2=A0 =C2=A021 ( 20 undocumented)
> Attributes: =C2=A0 91 ( 84 undocumented)
> Methods: =C2=A0 =C2=A0 822 (385 undocumented)
>
> Total: =C2=A0 =C2=A0 =C2=A01106 (580 undocumented)
> =C2=A047.56% documented

That's the oldest and most established subproject in rails... meaning, = it has the least excuse to be less than 50% documented.

For some reason Gmail doesn't show me the origin of th= is thread. But that remark seems unfair to me.

For starters, that statistic presented like that, cold,= is not very meaningful. You'd need to add how many of the undocumented= methods are public interface. Because we are talking about end users, to w= hich internal documentation is not a concern.

The documentation of Ruby on Rails has sure room for im= provement, but you can't deny that since docrails was created the docum= entation is good. We get many documentation contribs via docrails, the guid= es, patches are not accepted without docs coverage. Could it be better? Alw= ays, but this project has documentation as a first class citizen nowadays.<= /div>

I wanted to state my point of view. I have interest zer= o on discussing whether a certain adjective is appropriate or not.

Ruby has the same problem

No, Ruby has a wa= y worse problem.

I am not complaining (in open sou= rce I very rarely complain), but to express my opinion about this, it is a = matter of fact that Ruby documentation can't be compared with the quant= ity and quality of Rails documentation.

--e89a8f3b55885ba27f04be5e2746--