I find the Rails API difficult to use, in terms of finding the classes
and methods I want with a minimum number of mouse clicks. I don't
care if it uses RDoc or not, all I want is to find the information
quickly. At minimum, there should be one page where you can find all
classes listed alphabetically. I often forget the exact spelling of
the class or method, and the search bar can be helpful if I already
know what I'm looking for, but that's the point: if I don't know the
name, I want to browse all classes quickly, and choose a few that
might be relevant. Also, each method should list all possible
arguments and what they do, or at least a link to a page that gives a
common description. I do appreciate having a class directory
structure and further explanations as well, but it's often not the
first thing I'm looking for in an API.
For a good example, see the Ruby Core API: it lists all classes and
methods on one page, very easy to browse. Each class also has a list
of all classes in the left sidebar.
I understand this is driven by volunteers, and that it's based on data
collected from the Rails class source code. I appreciate all the
effort that's been put into it, and often I've found essential
information that kept my projects on track. But I also know I'm not
the first to comment on this, and probably won't be the last. This
ain't rocket science, folks, just basic UX.
> I find the Rails API difficult to use, in terms of finding the classes
> and methods I want with a minimum number of mouse clicks. I don't
> care if it uses RDoc or not, all I want is to find the information
> quickly. At minimum, there should be one page where you can find all
> classes listed alphabetically. I often forget the exact spelling of
> the class or method, and the search bar can be helpful if I already
> know what I'm looking for, but that's the point: if I don't know the
> name, I want to browse all classes quickly, and choose a few that
> might be relevant. Also, each method should list all possible
> arguments and what they do, or at least a link to a page that gives a
> common description. I do appreciate having a class directory
> structure and further explanations as well, but it's often not the
> first thing I'm looking for in an API.
> For a good example, see the Ruby Core API: it lists all classes and
> methods on one page, very easy to browse. Each class also has a list
> of all classes in the left sidebar.
> I understand this is driven by volunteers, and that it's based on data
> collected from the Rails class source code. I appreciate all the
> effort that's been put into it, and often I've found essential
> information that kept my projects on track. But I also know I'm not
> the first to comment on this, and probably won't be the last. This
> ain't rocket science, folks, just basic UX.
> -- > You received this message because you are subscribed to the Google Groups "Ruby on Rails: Documentation" group.
> To post to this group, send email to rubyonrails-docs@googlegroups.com.
> To unsubscribe from this group, send email to rubyonrails-docs+unsubscribe@googlegroups.com.
> For more options, visit this group at http://groups.google.com/group/rubyonrails-docs?hl=en.
But that is not as fast as usually an API is meant to be.
And I agree that the Ruby API documentation is a great example to be followed. Pretty easy to see examples and concise documentation.
Documenting Rails is not an easy task since it is a lot modular, so just extracting all documentation from the sources is often not enough...
I feel that the right way would be some custom organization pages that would group the classes by category and explain what they're useful for from a user's perspective.
But another issue is that the Rails core team just does't care much about API documentation as they care for the test suite for example.
It means that while developers are forced to write tests for each new feature, it seems they're not required to write proper documentation as well, as if it wasn't that important.
Implementation is what really matters in some's opinions and that is sad... :(
Here are some examples of organized documentation references:
I'm not saying that fixing the Rails API docs is an easy task, but we should at least admit that it is really in bad shape and doesn't transmit the great quality of the API itself.
I'm sorry that I don't have any practical suggestion for starting improving it. The only real solution in my opinion is for the Rails core team to change their mind.
It wouldn't worth making a big effort for organizing it and then seeing it become out-of-date in terms of organization because the pull requests and internal work don't mind in updating the docs as they change the API...
For example, "render" was once very well documented with tons of useful examples, but then they're gone for no apparent reason.
Maybe it became difficult to keep it up to date and they preferred to remove it so that they wouldn't need to maintain such documentation?
> I find the Rails API difficult to use, in terms of finding the classes
> and methods I want with a minimum number of mouse clicks. I don't
> care if it uses RDoc or not, all I want is to find the information
> quickly. At minimum, there should be one page where you can find all
> classes listed alphabetically. I often forget the exact spelling of
> the class or method, and the search bar can be helpful if I already
> know what I'm looking for, but that's the point: if I don't know the
> name, I want to browse all classes quickly, and choose a few that
> might be relevant. Also, each method should list all possible
> arguments and what they do, or at least a link to a page that gives a
> common description. I do appreciate having a class directory
> structure and further explanations as well, but it's often not the
> first thing I'm looking for in an API.
> For a good example, see the Ruby Core API: it lists all classes and
> methods on one page, very easy to browse. Each class also has a list
> of all classes in the left sidebar.
> I understand this is driven by volunteers, and that it's based on data
> collected from the Rails class source code. I appreciate all the
> effort that's been put into it, and often I've found essential
> information that kept my projects on track. But I also know I'm not
> the first to comment on this, and probably won't be the last. This
> ain't rocket science, folks, just basic UX.
I would honestly rather a curated site that contained a list of commonly used Rails methods and documentation for them, rather than an a hard-to-navigate auto-generated API, such as the one we have now.
On Saturday, 26 May 2012 at 10:33 PM, Rodrigo Rosenfeld Rosas wrote:
> I must agree that the Rails API docs are in very bad shape with regards to organization.
> Lots of empty classes in the sense that they don't have actually any documentation but we keep clicking on them.
> It is there just so that we can know that some method or class actually exist.
> Rails 1 used to have a great API documentation and it is sad that it continues to get worse :(
> Most of the time I'm looking for the documentation that I used to find in the API docs in the guides.
> For example, a common task is looking for controller's "render" documentation.
> If you try to look for render in the API docs, you'll find several "render" methods.
> But none of them have actual documentation. So usually I need to take a look at the guides to find some examples:
> But that is not as fast as usually an API is meant to be.
> And I agree that the Ruby API documentation is a great example to be followed. Pretty easy to see examples and concise documentation.
> Documenting Rails is not an easy task since it is a lot modular, so just extracting all documentation from the sources is often not enough...
> I feel that the right way would be some custom organization pages that would group the classes by category and explain what they're useful for from a user's perspective.
> But another issue is that the Rails core team just does't care much about API documentation as they care for the test suite for example.
> It means that while developers are forced to write tests for each new feature, it seems they're not required to write proper documentation as well, as if it wasn't that important.
> Implementation is what really matters in some's opinions and that is sad... :(
> Here are some examples of organized documentation references:
> I'm not saying that fixing the Rails API docs is an easy task, but we should at least admit that it is really in bad shape and doesn't transmit the great quality of the API itself.
> I'm sorry that I don't have any practical suggestion for starting improving it. The only real solution in my opinion is for the Rails core team to change their mind.
> It wouldn't worth making a big effort for organizing it and then seeing it become out-of-date in terms of organization because the pull requests and internal work don't mind in updating the docs as they change the API...
> For example, "render" was once very well documented with tons of useful examples, but then they're gone for no apparent reason.
> Maybe it became difficult to keep it up to date and they preferred to remove it so that they wouldn't need to maintain such documentation?
> Kind regards,
> Rodrigo.
> Em 25-05-2012 21:53, wookie escreveu: > > I find the Rails API difficult to use, in terms of finding the classes and methods I want with a minimum number of mouse clicks. I don't care if it uses RDoc or not, all I want is to find the information quickly. At minimum, there should be one page where you can find all classes listed alphabetically. I often forget the exact spelling of the class or method, and the search bar can be helpful if I already know what I'm looking for, but that's the point: if I don't know the name, I want to browse all classes quickly, and choose a few that might be relevant. Also, each method should list all possible arguments and what they do, or at least a link to a page that gives a common description. I do appreciate having a class directory structure and further explanations as well, but it's often not the first thing I'm looking for in an API. For a good example, see the Ruby Core API: it lists all classes and methods on one page, very easy to browse. Each class also has a list of all classes
in the left sidebar. I understand this is driven by volunteers, and that it's based on data collected from the Rails class source code. I appreciate all the effort that's been put into it, and often I've found essential information that kept my projects on track. But I also know I'm not the first to comment on this, and probably won't be the last. This ain't rocket science, folks, just basic UX.
> -- > You received this message because you are subscribed to the Google Groups "Ruby on Rails: Documentation" group.
> To post to this group, send email to rubyonrails-docs@googlegroups.com (mailto:rubyonrails-docs@googlegroups.com).
> To unsubscribe from this group, send email to rubyonrails-docs+unsubscribe@googlegroups.com (mailto:rubyonrails-docs+unsubscribe@googlegroups.com).
> For more options, visit this group at http://groups.google.com/group/rubyonrails-docs?hl=en.
>> I find the Rails API difficult to use, in terms of finding the classes
>> and methods I want with a minimum number of mouse clicks. I don't
>> care if it uses RDoc or not, all I want is to find the information
>> quickly. At minimum, there should be one page where you can find all
>> classes listed alphabetically. I often forget the exact spelling of
>> the class or method, and the search bar can be helpful if I already
>> know what I'm looking for, but that's the point: if I don't know the
>> name, I want to browse all classes quickly, and choose a few that
>> might be relevant. Also, each method should list all possible
>> arguments and what they do, or at least a link to a page that gives a
>> common description. I do appreciate having a class directory
>> structure and further explanations as well, but it's often not the
>> first thing I'm looking for in an API.
>> For a good example, see the Ruby Core API: it lists all classes and
>> methods on one page, very easy to browse. Each class also has a list
>> of all classes in the left sidebar.
>> I understand this is driven by volunteers, and that it's based on data
>> collected from the Rails class source code. I appreciate all the
>> effort that's been put into it, and often I've found essential
>> information that kept my projects on track. But I also know I'm not
>> the first to comment on this, and probably won't be the last. This
>> ain't rocket science, folks, just basic UX.
But still, don't you find value in keeping the documentation close to the method sources definition?
I mean, I second your suggestion, but I still think that those custom pages should extract part of the API from the sources so that they don't get outdated, don't you agree?
> I would honestly rather a curated site that contained a list of > commonly used Rails methods and documentation for them, rather than an > a hard-to-navigate auto-generated API, such as the one we have now.
> On Saturday, 26 May 2012 at 10:33 PM, Rodrigo Rosenfeld Rosas wrote:
>> I must agree that the Rails API docs are in very bad shape with >> regards to organization.
>> Lots of empty classes in the sense that they don't have actually any >> documentation but we keep clicking on them.
>> It is there just so that we can know that some method or class >> actually exist.
>> Rails 1 used to have a great API documentation and it is sad that it >> continues to get worse :(
>> Most of the time I'm looking for the documentation that I used to >> find in the API docs in the guides.
>> For example, a common task is looking for controller's "render" >> documentation.
>> If you try to look for render in the API docs, you'll find several >> "render" methods.
>> But none of them have actual documentation. So usually I need to take >> a look at the guides to find some examples:
>> But that is not as fast as usually an API is meant to be.
>> And I agree that the Ruby API documentation is a great example to be >> followed. Pretty easy to see examples and concise documentation.
>> Documenting Rails is not an easy task since it is a lot modular, so >> just extracting all documentation from the sources is often not enough...
>> I feel that the right way would be some custom organization pages >> that would group the classes by category and explain what they're >> useful for from a user's perspective.
>> But another issue is that the Rails core team just does't care much >> about API documentation as they care for the test suite for example.
>> It means that while developers are forced to write tests for each new >> feature, it seems they're not required to write proper documentation >> as well, as if it wasn't that important.
>> Implementation is what really matters in some's opinions and that is >> sad... :(
>> Here are some examples of organized documentation references:
>> I'm not saying that fixing the Rails API docs is an easy task, but we >> should at least admit that it is really in bad shape and doesn't >> transmit the great quality of the API itself.
>> I'm sorry that I don't have any practical suggestion for starting >> improving it. The only real solution in my opinion is for the Rails >> core team to change their mind.
>> It wouldn't worth making a big effort for organizing it and then >> seeing it become out-of-date in terms of organization because the >> pull requests and internal work don't mind in updating the docs as >> they change the API...
>> For example, "render" was once very well documented with tons of >> useful examples, but then they're gone for no apparent reason.
>> Maybe it became difficult to keep it up to date and they preferred to >> remove it so that they wouldn't need to maintain such documentation?
>> Kind regards,
>> Rodrigo.
>> Em 25-05-2012 21:53, wookie escreveu:
>>> I find the Rails API difficult to use, in terms of finding the classes
>>> and methods I want with a minimum number of mouse clicks. I don't
>>> care if it uses RDoc or not, all I want is to find the information
>>> quickly. At minimum, there should be one page where you can find all
>>> classes listed alphabetically. I often forget the exact spelling of
>>> the class or method, and the search bar can be helpful if I already
>>> know what I'm looking for, but that's the point: if I don't know the
>>> name, I want to browse all classes quickly, and choose a few that
>>> might be relevant. Also, each method should list all possible
>>> arguments and what they do, or at least a link to a page that gives a
>>> common description. I do appreciate having a class directory
>>> structure and further explanations as well, but it's often not the
>>> first thing I'm looking for in an API.
>>> For a good example, see the Ruby Core API: it lists all classes and
>>> methods on one page, very easy to browse. Each class also has a list
>>> of all classes in the left sidebar.
>>> I understand this is driven by volunteers, and that it's based on data
>>> collected from the Rails class source code. I appreciate all the
>>> effort that's been put into it, and often I've found essential
>>> information that kept my projects on track. But I also know I'm not
>>> the first to comment on this, and probably won't be the last. This
>>> ain't rocket science, folks, just basic UX.
On Saturday, 26 May 2012 at 10:33 PM, Rodrigo Rosenfeld Rosas wrote:
> I must agree that the Rails API docs are in very bad shape with regards to organization.
> Lots of empty classes in the sense that they don't have actually any documentation but we keep clicking on them.
> It is there just so that we can know that some method or class actually exist.
> Rails 1 used to have a great API documentation and it is sad that it continues to get worse :(
> Most of the time I'm looking for the documentation that I used to find in the API docs in the guides.
> For example, a common task is looking for controller's "render" documentation.
> If you try to look for render in the API docs, you'll find several "render" methods.
> But none of them have actual documentation. So usually I need to take a look at the guides to find some examples:
> But that is not as fast as usually an API is meant to be.
> And I agree that the Ruby API documentation is a great example to be followed. Pretty easy to see examples and concise documentation.
> Documenting Rails is not an easy task since it is a lot modular, so just extracting all documentation from the sources is often not enough...
> I feel that the right way would be some custom organization pages that would group the classes by category and explain what they're useful for from a user's perspective.
> But another issue is that the Rails core team just does't care much about API documentation as they care for the test suite for example.
> It means that while developers are forced to write tests for each new feature, it seems they're not required to write proper documentation as well, as if it wasn't that important.
> Implementation is what really matters in some's opinions and that is sad... :(
> Here are some examples of organized documentation references:
> I'm not saying that fixing the Rails API docs is an easy task, but we should at least admit that it is really in bad shape and doesn't transmit the great quality of the API itself.
> I'm sorry that I don't have any practical suggestion for starting improving it. The only real solution in my opinion is for the Rails core team to change their mind.
> It wouldn't worth making a big effort for organizing it and then seeing it become out-of-date in terms of organization because the pull requests and internal work don't mind in updating the docs as they change the API...
> For example, "render" was once very well documented with tons of useful examples, but then they're gone for no apparent reason.
> Maybe it became difficult to keep it up to date and they preferred to remove it so that they wouldn't need to maintain such documentation?
> Kind regards,
> Rodrigo.
> Em 25-05-2012 21:53, wookie escreveu: > > I find the Rails API difficult to use, in terms of finding the classes and methods I want with a minimum number of mouse clicks. I don't care if it uses RDoc or not, all I want is to find the information quickly. At minimum, there should be one page where you can find all classes listed alphabetically. I often forget the exact spelling of the class or method, and the search bar can be helpful if I already know what I'm looking for, but that's the point: if I don't know the name, I want to browse all classes quickly, and choose a few that might be relevant. Also, each method should list all possible arguments and what they do, or at least a link to a page that gives a common description. I do appreciate having a class directory structure and further explanations as well, but it's often not the first thing I'm looking for in an API. For a good example, see the Ruby Core API: it lists all classes and methods on one page, very easy to browse. Each class also has a list of all classes
in the left sidebar. I understand this is driven by volunteers, and that it's based on data collected from the Rails class source code. I appreciate all the effort that's been put into it, and often I've found essential information that kept my projects on track. But I also know I'm not the first to comment on this, and probably won't be the last. This ain't rocket science, folks, just basic UX.
> -- > You received this message because you are subscribed to the Google Groups "Ruby on Rails: Documentation" group.
> To post to this group, send email to rubyonrails-docs@googlegroups.com (mailto:rubyonrails-docs@googlegroups.com).
> To unsubscribe from this group, send email to rubyonrails-docs+unsubscribe@googlegroups.com (mailto:rubyonrails-docs+unsubscribe@googlegroups.com).
> For more options, visit this group at http://groups.google.com/group/rubyonrails-docs?hl=en.
> That has traditionally not worked well. We need an alternative solution.
Yeah, but the main reason is that Rails developers don't seem to care about keeping their changes reflected in the documentation.
A separate effort to track the changes from the commit log and update the parallel documentation updated would be a full-time work.
*That* won't work in my opinion.
If Rails committers are not going to change their mind with regards to documentation importance I simply can't see any solution to fix Rails bad API docs.
>>> I find the Rails API difficult to use, in terms of finding the classes
>>> and methods I want with a minimum number of mouse clicks. I don't
>>> care if it uses RDoc or not, all I want is to find the information
>>> quickly. At minimum, there should be one page where you can find all
>>> classes listed alphabetically. I often forget the exact spelling of
>>> the class or method, and the search bar can be helpful if I already
>>> know what I'm looking for, but that's the point: if I don't know the
>>> name, I want to browse all classes quickly, and choose a few that
>>> might be relevant. Also, each method should list all possible
>>> arguments and what they do, or at least a link to a page that gives a
>>> common description. I do appreciate having a class directory
>>> structure and further explanations as well, but it's often not the
>>> first thing I'm looking for in an API.
>>> For a good example, see the Ruby Core API: it lists all classes and
>>> methods on one page, very easy to browse. Each class also has a list
>>> of all classes in the left sidebar.
>>> I understand this is driven by volunteers, and that it's based on data
>>> collected from the Rails class source code. I appreciate all the
>>> effort that's been put into it, and often I've found essential
>>> information that kept my projects on track. But I also know I'm not
>>> the first to comment on this, and probably won't be the last. This
>>> ain't rocket science, folks, just basic UX.
> -- > You received this message because you are subscribed to the Google Groups "Ruby on Rails: Documentation" group.
> To post to this group, send email to rubyonrails-docs@googlegroups.com.
> To unsubscribe from this group, send email to rubyonrails-docs+unsubscribe@googlegroups.com.
> For more options, visit this group at http://groups.google.com/group/rubyonrails-docs?hl=en.
>>>> I find the Rails API difficult to use, in terms of finding the classes
>>>> and methods I want with a minimum number of mouse clicks. I don't
>>>> care if it uses RDoc or not, all I want is to find the information
>>>> quickly. At minimum, there should be one page where you can find all
>>>> classes listed alphabetically. I often forget the exact spelling of
>>>> the class or method, and the search bar can be helpful if I already
>>>> know what I'm looking for, but that's the point: if I don't know the
>>>> name, I want to browse all classes quickly, and choose a few that
>>>> might be relevant. Also, each method should list all possible
>>>> arguments and what they do, or at least a link to a page that gives a
>>>> common description. I do appreciate having a class directory
>>>> structure and further explanations as well, but it's often not the
>>>> first thing I'm looking for in an API.
>>>> For a good example, see the Ruby Core API: it lists all classes and
>>>> methods on one page, very easy to browse. Each class also has a list
>>>> of all classes in the left sidebar.
>>>> I understand this is driven by volunteers, and that it's based on data
>>>> collected from the Rails class source code. I appreciate all the
>>>> effort that's been put into it, and often I've found essential
>>>> information that kept my projects on track. But I also know I'm not
>>>> the first to comment on this, and probably won't be the last. This
>>>> ain't rocket science, folks, just basic UX.
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.
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.
> -- > You received this message because you are subscribed to the Google Groups "Ruby on Rails: Documentation" group.
> To post to this group, send email to rubyonrails-docs@googlegroups.com (mailto:rubyonrails-docs@googlegroups.com).
> To unsubscribe from this group, send email to rubyonrails-docs+unsubscribe@googlegroups.com (mailto:rubyonrails-docs+unsubscribe@googlegroups.com).
> For more options, visit this group at http://groups.google.com/group/rubyonrails-docs?hl=en.
> 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.
Docrails has helped a lot indeed when it was introduced, but then the API got worse and worse despite the continued use of docrails.
And that is not the contributor's fault, but the core member ones that didn't show any respect for previous hard work of those who spent a considerable amount of time writing such well written API method descriptions full of detailed explanations and examples.
They seem to have just removed useful documentation as if it wasn't so much valuable. Maybe they didn't figure out where to put that documentation and found it easier to just get rid of it so that they could spend their time on the refactoring itself.
Maybe I'm just guessing, but I didn't get any reasonable explanations for that so far.
> 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.
I don't see things that way. The fact that we use open-source software, which is mostly done as volunteer work, doesn't mean that we shouldn't be allowed to complain.
How would things get better if they're not discussed? The result may be that at some point people will stop using Rails and start using another similar framework which has better API documentation, since this is very important to developers using some framework.
Lots of people would be affected if that changes. If less people are using Rails, there will be less job offers for it for those who work at some company.
For those working on consulting or training, they would get less clients each time.
And if the community gets smaller we would get less and less available interesting new gems, or get some gems to be abandoned.
Currently there are lots of good web frameworks popping out there and Rails is still my choice of preference, specially for Sprockets integration.
But at some point lots of other frameworks will become as attractive as Rails and will probably perform better with proper threading model, good API documentation, etc.
So, if we don't make an effort to keep Rails a breeze to work with (and API matters a lot), we'll be taking the risk of losing several years specializing ourselves in Rails and investing time in writing our gems.
We can't just stop ourselves from complaining just because some library is based on volunteer work. Which library doesn't work this way nowadays?
What I'm just proposing here is some reflection on our current development mode as we can't force anyone to change. We can only expose our point of view and hope them to understand them and embrace them.
I'm trying to make a point here that it won't be possible to maintain a great API documentation for Rails if there isn't any explicit rules about that in the commit and pull request policies. I mean to the extreme to revert some commits just because they changed and API and didn't reflect that change in the documentation.
Any other efforts, like a separate team for documenting changes or a Wiki will just make things worse and we'll never be able to really trust the documentation.
I agree that we can write separate pages for better organizing and split the API in sections, but in the method level, it should be integrated in the source code.
Remember when teams used to be split in developers, testers and documenters?
Rails did a great job in joining the developers and testers as one as they understood that those teams can't work separately.
But some didn't understand yet that the same applies for the API.
> 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."
This is more a workaround than a proper way of doing this. Usually contributors are concerned about features or bugs that are of interest for them.
While doing that, that is ok for them to update the documentation to reflect their changes.
But hoping that some developers will be volunteering just to help on documentation... There are not much people like you in the World, Xavier.
Thank you very much for your brave effort by the way. They're greatly appreciate by so many developers out there.
But talking for myself, when I had previously contributed to Rails, either with patches or documentation fixes, I did that when I found some error while looking at the documentation or when I missed some information or when I was missing some feature.
I never watch the rails-core commit log. And I guess most contributors are like me and just a few will be actually reviewing all commits that go to master...
> 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.
+1000
> 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.
I totally support your ideas.
> 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 don't really thing this effort worths, but I'm not against it. I must admit that I haven't think much about this to be against it too :)
> 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.
What about methods whose return values shouldn't have any meanings? For example, I usually see some people coding this way:
render 'something' and return if condition?
I don't support this style and would recommend something like this instead:
(render 'something'; return) if condition?
That is because 'render' return value shouldn't have any special meaning so you shouldn't count on it returning a truthy value.
As long as @return tags aren't required, I support this addition.
> Thanks for raising these concerns,
I must thank you for all the actual brave hard work you keep putting on Rails documentation despite all problems we're aware of.
Complaining is the easiest part ;) Nothing to thank about :)
> 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.
On Sunday, 27 May 2012 at 10:27, Rodrigo Rosenfeld Rosas wrote:
> 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.
> -- > You received this message because you are subscribed to the Google Groups "Ruby on Rails: Documentation" group.
> To post to this group, send email to rubyonrails-docs@googlegroups.com.
> To unsubscribe from this group, send email to rubyonrails-docs+unsubscribe@googlegroups.com.
> For more options, visit this group at http://groups.google.com/group/rubyonrails-docs?hl=en.
Well, I would not say automated docs have not worked. I think we've
got a much better API over the time, and I can tell you there has been
an internal shift, core team members are more aware of documentation.
Some are more sensible to this topic than others, but I think things
are gradually changing towards the positive.
I also think the current situation is not bad, though as we all agree
there is room for improvement in several aspects.
But the way to influence in this change, in my way to see these
things, is to act. You care? Go fix stuff. That's why I was first in
the line years ago when Pratik announced docrails. Docs were a pain
point for me and docrails gave me the opportunity to do something
about this.
And that percolates with time. For example, we no longer have a
documentation team (it was Pratik, Mike Gunderloy, and me
myself in the past). Why? Because of what Rodrigo said, a
documentation team is analogous to a testing team. Docs have
matured, and when I became a core team member I suggested
that a doc team defined as such did make sense anymore,
docs have to be maintained by everyone, in every single patch.
The message to convey is: documentation is first-class citizen.
Documentation is maintained *in master*. Every patch should come with
code, test, and docs. Pull requests, and core team member
contributions.
That is why docrails is not "marketed" as a documentation project.
docrails is for quick fixes (and guide authors for convenience).
Documentation maintenance happens *in master*. There is no
documentation project.
And Rails has no "documenters" either. The same way it has no
"testers". Everyone should document what they add. I don't expect
everyone to know the doc guidelines. Heck, even today there are a
small number of core team members that write "ActiveRecord" (?!?!?!).
And not everyone is skilled to explain things, etc. So, I never say
"hey, please put this class name in fixed-width font. Please write
MySQL instead of Mysql. Please reword this sentence". Rather, we
accept the docs gladly and copy-edit, but the docs should
be there with the patch.
Because of all of that I don't believe in wikis too much. It sends the
wrong message, it says docs are some external thing maintained by
other people. Nope, docs are/should be a first-class citizen of the
project, and when you modify something, or add something, the patch
should be complete. Everything kept in sync in the very patch.
And I think docs are more first-class citizens in Rails than they we
three four years ago. I know for certain they have gained weight and
we go in the positive direction. People mention more docs in PRs, and
it is more normal that you get a warning if your patch does not touch
the docs.
My proposal is: let's work, let's be constructive, let's put in
practice our beliefs and push by osmosis, give example.
Ryan itself has written guides, that's the way to move this forward.
Vijay is doing an extraordinaire work with docrails and PRs. Really
amazing, I can tell you guys doing what Vijay is doing is hard: you
need to monitor every single commit in docrails, to any part of the
code base, and you need to review, comment, or revert. Vijay
deserves a big hurray if we guys ever meet in a conference (we
should! :).
Let's do the README, let's get a more intelligent way to compute
ancestor chains so that a user of AR::Base is able to check the ~700
hundred methods his models respond to. Let's write guides.
The outcome of something like this can only be positive. There is
always going to be some imperfection here and there, but in the long
run it will be worthwhile. The same way I look back fours years and
think it has been worthwhile.
What I'm mostly concerned with is what I stated in my last message.
Why would someone invest a considerable effort for creating a superb documentation do ActionController::Base#render if some core members won't show any respect for them by removing the docs while refactoring the code base?
That is the most frustrating experience. I'm not inclined to spend time fixing documentation if the core members don't care enough about it and won't hesitate in removing it when it seems appropriate to them.
> Well, I would not say automated docs have not worked. I think we've
> got a much better API over the time, and I can tell you there has been
> an internal shift, core team members are more aware of documentation.
> Some are more sensible to this topic than others, but I think things
> are gradually changing towards the positive.
> I also think the current situation is not bad, though as we all agree
> there is room for improvement in several aspects.
> But the way to influence in this change, in my way to see these
> things, is to act. You care? Go fix stuff. That's why I was first in
> the line years ago when Pratik announced docrails. Docs were a pain
> point for me and docrails gave me the opportunity to do something
> about this.
> And that percolates with time. For example, we no longer have a
> documentation team (it was Pratik, Mike Gunderloy, and me
> myself in the past). Why? Because of what Rodrigo said, a
> documentation team is analogous to a testing team. Docs have
> matured, and when I became a core team member I suggested
> that a doc team defined as such did make sense anymore,
> docs have to be maintained by everyone, in every single patch.
> The message to convey is: documentation is first-class citizen.
> Documentation is maintained *in master*. Every patch should come with
> code, test, and docs. Pull requests, and core team member
> contributions.
> That is why docrails is not "marketed" as a documentation project.
> docrails is for quick fixes (and guide authors for convenience).
> Documentation maintenance happens *in master*. There is no
> documentation project.
> And Rails has no "documenters" either. The same way it has no
> "testers". Everyone should document what they add. I don't expect
> everyone to know the doc guidelines. Heck, even today there are a
> small number of core team members that write "ActiveRecord" (?!?!?!).
> And not everyone is skilled to explain things, etc. So, I never say
> "hey, please put this class name in fixed-width font. Please write
> MySQL instead of Mysql. Please reword this sentence". Rather, we
> accept the docs gladly and copy-edit, but the docs should
> be there with the patch.
> Because of all of that I don't believe in wikis too much. It sends the
> wrong message, it says docs are some external thing maintained by
> other people. Nope, docs are/should be a first-class citizen of the
> project, and when you modify something, or add something, the patch
> should be complete. Everything kept in sync in the very patch.
> And I think docs are more first-class citizens in Rails than they we
> three four years ago. I know for certain they have gained weight and
> we go in the positive direction. People mention more docs in PRs, and
> it is more normal that you get a warning if your patch does not touch
> the docs.
> My proposal is: let's work, let's be constructive, let's put in
> practice our beliefs and push by osmosis, give example.
> Ryan itself has written guides, that's the way to move this forward.
> Vijay is doing an extraordinaire work with docrails and PRs. Really
> amazing, I can tell you guys doing what Vijay is doing is hard: you
> need to monitor every single commit in docrails, to any part of the
> code base, and you need to review, comment, or revert. Vijay
> deserves a big hurray if we guys ever meet in a conference (we
> should! :).
> Let's do the README, let's get a more intelligent way to compute
> ancestor chains so that a user of AR::Base is able to check the ~700
> hundred methods his models respond to. Let's write guides.
> The outcome of something like this can only be positive. There is
> always going to be some imperfection here and there, but in the long
> run it will be worthwhile. The same way I look back fours years and
> think it has been worthwhile.
On Sun, May 27, 2012 at 6:16 PM, Rodrigo Rosenfeld Rosas
<rr.ro...@gmail.com> wrote:
> What I'm mostly concerned with is what I stated in my last message.
> Why would someone invest a considerable effort for creating a superb
> documentation do ActionController::Base#render if some core members won't
> show any respect for them by removing the docs while refactoring the code
> base?
> That is the most frustrating experience. I'm not inclined to spend time
> fixing documentation if the core members don't care enough about it and
> won't hesitate in removing it when it seems appropriate to them.
It could be an overlook, in the Rails 3 days refactors were really wild.
But trust me, there is really no reason to generalize that, and we
cannot for certain generalize the attitude of the core team. Some
people care less, for example, do not have the habit of requesting
docs coverage to accept a pull request. For some reason this is not in
their radar. But other people in core and committers do care, and I am
confident that's the trend.
And if you ask me, this is just a particular case of the fact that
docs are traditionally weak in the Ruby culture. For whatever reason
(I have a talk on that topic). We are light years from Perl.
> On Sun, May 27, 2012 at 6:16 PM, Rodrigo Rosenfeld Rosas
> <rr.ro...@gmail.com> wrote:
>> What I'm mostly concerned with is what I stated in my last message.
>> Why would someone invest a considerable effort for creating a superb
>> documentation do ActionController::Base#render if some core members won't
>> show any respect for them by removing the docs while refactoring the code
>> base?
>> That is the most frustrating experience. I'm not inclined to spend time
>> fixing documentation if the core members don't care enough about it and
>> won't hesitate in removing it when it seems appropriate to them.
> It could be an overlook, in the Rails 3 days refactors were really wild.
git log -S "Rendering an action"
commit 19c3495a671c364e0dc76c276efbcd9dc6914c74
Author: Yehuda Katz + Carl Lerche <ykatz+cler...@engineyard.com>
Date: Mon Jun 15 16:29:45 2009 -0700
rm -r controller/base!
And suddenly lots of useful documentation written with care just went away.
This means only testing matters. As long as tests pass go for it.
> But trust me, there is really no reason to generalize that, and we
> cannot for certain generalize the attitude of the core team.
I didn't generalize. I always said "some of the rails core developers". But the effect is the same. A single developer working this way will suffice to remove useful documentation.
> Some people care less, for example, do not have the habit of requesting
> docs coverage to accept a pull request. For some reason this is not in
> their radar. But other people in core and committers do care, and I am
> confident that's the trend.
> And if you ask me, this is just a particular case of the fact that
> docs are traditionally weak in the Ruby culture. For whatever reason
> (I have a talk on that topic). We are light years from Perl.
I certainly don't agree. I used to do web development in Perl before I started with Rails in 2007.
I wasn't doing web development for some years at that time having spent the last years working with real-time stuff with C and C++ on Xenomai and Kernel modules developing.
When I changed my job in 2007 I would be back to web development and decided to look for recent web frameworks as I wasn't much satisfied with the state of Perl.
So I evaluated lots of them, like TurboGears, Django, J2EE, MS Dot Net and a few other options and Rails became my choice, specially because it was very well documented. I guess it was about version 1.0 or 1.1 at that time.
One of my selling points when trying to convince others to move to Rails was its very well documented API, full with great examples. This wasn't certainly the norm in the Perl community or any other I've searched at that time.
The only drawback I saw in Rails by that time was the lack of internationalization support, but at the end I decided for Rails instead of TurboGears, my second option. I didn't know Ruby or Python by that time, so I didn't care much about the language, but the Rails migrations tool was the key point for my choice by that time. And I'm happy I opted for it.
Rails wasn't the only well documented Ruby gem. I found in the Ruby community a great experience with regards to documentation that I haven't found in other communities.
I've been doing mostly Java and Groovy (Grails) development since 2009 when I changed my job. And their documentation was really bad. I managed to convince them a while ago to adopt the docrails model for their User's Guide, which is a separate project, and the documentation has gotten much better in the last months. But their Java API are in really bad shape as most Java API I've been working with.
After that I changed my job again last year, but my new company wanted me to maintain another Grails application.
Due to some recent Grails critical bug that I've reported a few months ago and that is still unfixed, I decided to create a new Rails application and proxy the affected requests to it. This happened about one or two months ago. Since then I'm back to Ruby and Rails development and I can clearly see the difference with regards to Rails documentation from 2007 to 2009 and the current situation and they're a totally different experience.
Now I'm working mostly with Rails again, porting the old application to the newest one written with Rails in chunks. So I'm re-getting familiar with the current state of Ruby gems and Rails again.
Here is my experience with great documentation I've found so far:
As you can see, all libraries I'm currently using are pretty well documentation, because this is very important to me.
I just opted for Rails in 2007 because it used to have a superb well documented API and guides.
While the guides are still excellent and getting better and better, the same can't be said of the API documentation itself. It used to be great in Rails 1, but it is not in Rails 3.
I agree that changing the main page is a required change now that Rails needs some more organized API since it is more modular, which is great. But while a great job was done in the code base during the Rails 3 refactoring, not enough care was driven to the documentation and then lots of great resources were just trashed at no absolute reason. And that is the sad thing.
I don't really intend to invest a considerable amount of time working on documentation improvements for Rails unless *all* core team members take documentation as serious as they take testing.
My time is limited and I always try to make better use of it. Currently I've been focused on some testing effort for JavaScript:
Here are some repositories I've been working with in the last days:
There are other projects I've been involved with in the last weeks as well, like Sequel and jqTree. My previous experience trying to contribute to Rails and Gitorious in the past have been so bad that I'll hardly consider contributing to those projects, since they usually consume a lot of my little free time for so little result. Usually I'll prefer to use my time to work on those other projects.
I do even intend to write an article on good practices about client-side code testing writing later after I take a nap. So, there are so many projects I'd like to work on and so little free time that I'll hardly opt for working in a task that some people of the core team don't seem to see as much value as I do.
On Sun, May 27, 2012 at 9:07 PM, Rodrigo Rosenfeld Rosas
<rr.ro...@gmail.com> wrote:
> git log -S "Rendering an action"
> commit 19c3495a671c364e0dc76c276efbcd9dc6914c74
> Author: Yehuda Katz + Carl Lerche <ykatz+cler...@engineyard.com>
> Date: Mon Jun 15 16:29:45 2009 -0700
> rm -r controller/base!
> And suddenly lots of useful documentation written with care just went away.
> This means only testing matters. As long as tests pass go for it.
Well, from one particular commit you derive too many things. Yehuda
recently worked on some new stuff, and when they pushed there was a
complete guide.
> And if you ask me, this is just a particular case of the fact that
> docs are traditionally weak in the Ruby culture. For whatever reason
> (I have a talk on that topic). We are light years from Perl.
> I certainly don't agree. I used to do web development in Perl before I
> started with Rails in 2007.
> I wasn't doing web development for some years at that time having spent the
> last years working with real-time stuff with C and C++ on Xenomai and Kernel
> modules developing.
> When I changed my job in 2007 I would be back to web development and decided
> to look for recent web frameworks as I wasn't much satisfied with the state
> of Perl.
But I wasn't talking about web frameworks, I was talking about
documentation in the community.
I know the Perl community well, was into Perl for about six years, I
am a CPAN author and former leader of the local group Barcelona.pm, a
regular in Freenode#perl for years etc.
Documentation in the Perl community is *strong*. I have yet to find a
community that excels at documentation the way the Perl community
does.
On one hand, take any Unix machine and type
perldoc perl
That long man page is just the fucking *table of contents* of the
builtin documentation of the *language*. The language! Compare that
with what you get from Ruby. And the docs are maintained by the core
devs of the interpreter. If you patch something in perl5-porters, you
patch the docs.
And any CPAN author is expected to profusely document their modules,
using the standard organization. Also, the docs are good and
pragmatic, as anything related to Perl.
In Ruby, that level of commitment to providing documentation is light
years away from what is standard in Perl.
That does not mean there are no gems well-documented. I am talking
about what's the norm at the community level.
