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