Rails API difficult to use - Ruby on Rails: Documentation

The old Google Groups will be going away soon, but your browser is incompatible with the new version.
Message from discussion Rails API difficult to use
Received-SPF: pass (google.com: domain of rr.ro...@gmail.com designates 209.85.212.45 as permitted sender) client-ip=209.85.212.45;
Message-ID: <4FC1750A.80...@gmail.com>
Date: Sat, 26 May 2012 21:27:54 -0300
From: Rodrigo Rosenfeld Rosas <rr.ro...@gmail.com>
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:10.0.4) Gecko/20120510 Icedove/10.0.4
MIME-Version: 1.0
To: rubyonrails-docs@googlegroups.com
Subject: Re: [Rails-docs] Rails API difficult to use
References: <eadcedf4-9905-4bb9-b09f-535f54687...@st3g2000pbc.googlegroups.com> <21A07303-7560-48EA-B0A5-DF6E1C8CB...@comcast.net> <4FC0CEF5.8060...@gmail.com> <F057C5CD-7685-43B6-81A3-BC268AF84...@comcast.net> <4FC0E581.1020...@gmail.com> <CAM=Ycdgjf5J6uixudT1ka5Y=GBEG5iSkCpWEKsQ8_5ZnPAU...@mail.gmail.com> <09EAC1AC8D6946629C493CD6DB941...@gmail.com>
In-Reply-To: <09EAC1AC8D6946629C493CD6DB941...@gmail.com>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit

docrails is already a wiki-like tool. I don't understand why you think 
that using another interface for it would make much difference...

Em 26-05-2012 20:18, Ryan Bigg escreveu:
> Would re-introducing the wiki work? I think a wiki would be a great 
> source for cultivating information. I understand that the previous one 
> fell into disrepair, but that's ok. We could host this one on the 
> GitHub project's page and work on it there.
>
> On Sunday, 27 May 2012 at 5:53 AM, Xavier Noria wrote:
>
>> Yeah, the API needs love.
>>
>> It was much worse in the past, docrails has made the API way better,
>> meaning it has more content. Content was the most urgent weak point to
>> fix, and there is now more content. Though it is not enough.
>>
>> The core team nowadays looks for docs a little bit more. We are far
>> from a generic discipline like the one practiced to keep the test
>> suite unfortunately. For some reason or another, some people put more
>> love on this than others. I don't understand that to be honest, but I
>> don't personally complain because this is volunteer work (for most of
>> us). The only thing we can do is to give a positive example to try to
>> make things change with time.
>>
>> For instance, contributors may raise awareness constructively by
>> keeping an eye on the pull requests and comment, "hey, this patch
>> lacks such and such update the API. Should update these twelve
>> examples scattered over the code base. Should update this and that
>> guide. Etc."
>>
>> One think I'd like to do is to change the main page. That is a simple
>> change but can make a difference. The main page of the API no longer
>> needs to play the role of a README. We could have a dedicated main
>> page. And I thought about having "entry points" there.
>>
>> Like, sections per layers or something like that. And links to the
>> most used stuff, validations, filters, helper methods, mailers, etc.
>> Always keeping in mind the API is a reference, the howto role is
>> played by guides. So I envision an index of some sort, nicely
>> presented, but dry.
>>
>> One thing I want to do for Rails 4 is to implement that plan sometimes
>> I've explained of executing the Rails code base to introspect and
>> build a better ancestor chain. It would not be a new tool, rather a
>> RDoc or YARD plugin that would replace the structure they build. For
>> example, the page of ActionController::Base is now mostly empty. And
>> there are other examples, one hundred uses of AS::Concern and other
>> dynamic stuff that make parsers too limited for Rails.
>>
>> I'd love to document types in a formal way. I do believe it works and
>> makes the API much better. But that would required a lot of discipline
>> in core itself. Everyone should write @return tags etc. Something like
>> that should be an decision taken at the project level.
>>
>> Thanks for raising these concerns,
>>
>> Xavier
>>
>> PS: The docs of the render method were probably lost somewhere in the
>> wild refactors of Rails 3.
>>
Create a group - Google Groups - Google Home - Terms of Service - Privacy Policy
Account Options
