From: Josh Vaughn Date: 2011-08-03T05:10:59+09:00 Subject: Re: Documentation Improvement Proposal --0-1042702187-1312315480=:90030 Content-Type: text/plain; charset=iso-8859-1 Content-Transfer-Encoding: quoted-printable Hello,=0AI have been out of so to speak developing for a little while and g= o interested in Ruby. So, I am picking it up. With that I have a bit of a d= ifferent view and that is of someone who would live to see some good docume= ntation and APIs. So with that I took a look at some languages I have used = int he past Python, PHP, Java and found that PHP was pretty darn good next = would be Python as it was similar to PHP. Javadoc is OK, but for someone ne= w it is very daunting. As far as user input for the documentation; if set u= p correctly I see no issue. Example that I did just yesterday.=0A=0Aary =3D= Array.new(r, Array.new(10))=0Avs=0Aary =3D Array.new(10) { Array.new(10) }= =0A=0ASeemingly the same, but they are not. User documentation might say th= e best way to do multi-dimensional array. Note I am learning and tried the = first as I found that Array.new(some initial size, some initial value) was = the basic Array API.=0A=0AAnyway, this is my two cents.=0A=0A--=0AJoshua Va= ughn=0A=0A=0A>________________________________=0A>From: Phillip Gawlo= wski <cmdjackryan@gmail.com>=0A>To: ruby-talk ML <ruby-talk@rub= y-lang.org>=0A>Sent: Tuesday, August 2, 2011 1:47 PM=0A>Subject: R= e: Documentation Improvement Proposal=0A>=0A>On Tue, Aug 2, 2011 at 7= :39 PM, Steve Klabnik <steve@steveklabnik.com> wrote:=0A>>=0A&g= t;> That said, if any of you follow me on Twitter, you'll have seen = the=0A>> zillions of tweets I sent out today about this; I _do_ think= that=0A>> Ruby's documentation needs a lot of work. I'm not = sure that a huge,=0A>> heavy-handed process is the right way, though.= =0A>=0A>What's wrong with stealing WikiPedia's procedures? Th= e model works=0A>quite well, even for narrower topics (Like Memory Alpha= , the Fallout=0A>Wiki, and the Portland Pattern Repository show).=0A>= =0A>Don't mistake a centralised approach with a heavy handed, monoli= thic,=0A>cathedral-style process. :)=0A>=0A>-- =0A>Phillip Gawl= owski=0A>=0A>phgaw.posterous.com | twitter.com/phgaw | gplus.to/phgaw= =0A>=0A>A method of solution is perfect if we can forsee from the sta= rt,=0A>and even prove, that following that method we shall attain our ai= m.=0A>=A0 =A0 =A0 =A0 =A0 =A0 =A0 -- Leibniz=0A>=0A>=0A>=0A> --0-1042702187-1312315480=:90030--