Rails API difficult to use

rubyonrails-docs
1

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.

2

like this? http://apidock.com/rails/browse

3

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 :frowning:

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:

http://guides.rubyonrails.org/action_controller_overview.html

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… :frowning:

Here are some examples of organized documentation references:

http://rubydoc.info/gems/sinatra http://grails.org/doc/latest/ (user’s guide mixed with API in the right side) http://rubydoc.info/github/merb/merb/master/frames http://sequel.rubyforge.org/documentation.html (notice on how the docs are organized in topics) http://api20.cakephp.org/class/controller

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.
4

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.

5

Why can’t I find this in the main API link (http://api.rubyonrails.org/)?

http://apidock.com/rails/ActionController/Base/render

Also, it is a shame that the main API still uses frames.

This way you can't send some one the link for some specific part of

the documentation in a browseable way…

6

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?

7

That has traditionally not worked well. We need an alternative solution.

8

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.

9

because it’s a list of classes, not methods

it doesn’t meet your “browsable” requirement, but the search box will find the render method for you.

10

Sorry, I guess I wasn’t clear in my question.

I was asking why I can't find the documentation of render, which is

present in the apidock version, in the main API link.

Was it removed at some point? It means this documentation was there

at v2.3.8. So, why removing it?

11

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.

12

Ugh I wrote that quickly and realize now there are some typos, sorry for that!

13

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.

14

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.

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 :slight_smile:

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 :wink: Nothing to thank about :slight_smile:

Cheers, Rodrigo.

15

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

16

No problems about that. I do that all the time :slight_smile: Better to express our opinions than to spend too much time reviewing our messages :wink:

17

Because automated doc gen tools have not worked. I think a wiki would work.

18

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.

19

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.

No one like reworking. :frowning:

20

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.