Comment by viraptor | Hacker News Reader

Comment by viraptor | Hacker News Reader

Parent Full thread

I'm not a rails person, but I had a look at the api docs he decided to link as an example... And I understood why people might be complaining.

I started with railsapi.com - selected something at random: first ActionView::Layouts (seems like a crucial class):

    find_layout(layout) - This is the method which actually
    finds the layout using details in the lookup context
    object. If no layout is found, it checks if at least a
    layout with the given name exists across all details
    before raising the error."

Right... where does the "lookup context" object go? What is "layout" What's returned? Where does it "find the layout"? Why does this method exist? What error is raised? Ok - maybe I just chose something that's not popular - another try is ActionView::PathResolver:

    to_path() - Alias for to_s
    to_s() - This method is also aliased as to_path

You're kidding me, right? Ok - something easy this time - "Float" -> "round(precision = nil) - Rounds the float with the specified precision." Rounds which way? What type of rounding is used? How does it behave for infinities and -epsilon? Something important "I18n" - there is NO documentation at all.

I checked APIdock, thinking it might be better - it took a lot of clicking to get to a class which had any documentation at all (ActiveRecord in this case). If you check "browse", you'll see yourself how many classes lack any kind of description...

Summing up - I'm not sure about the screencasts, guides, etc., but API docs are almost non-existent.

Rails is not a library. It wouldn't serve anybody to write a dissertation in every file about how that file fits into the whole framework.

Rails API documentation is far from perfect, but a surprising amount of the important stuff is covered in a few consolidated locations. The documentation for some modules is often consolidated in a more central location so you can get a better overview of the whole API. See ActionController::Base, ActiveRecord::Base, ActiveRecord::Associations::ClassMethods for example. As for I18n, well, I18n is an external gem, it is not core to Rails which is why it is not documented there.

No one is arguing that Rails API documentation is newbie friendly, but I would argue that the purpose of API documentation is not to introduce people to the framework; it's reference material. The Rails Guides are pretty good (if not lagging a bit for some aspects of Rails 3) and I would put them up against any other framework documentation I've used.

For better or worse, I'm convinced that this is the reason that PHP took off the way it did. The documentation was clear, concise, easy to access (perhaps the first example of user friendly URLs I can remember), and effective; That each function had user-submitted (moderated) comments was the icing on the cake.

Being able to look at a function, have clear documentation WITH EXAMPLES was brilliant -- being able to see some of the common questions and resolutions from users was exemplary.

I know that the python docs are largely considered aces, but I have yet to see a language reference as good as the PHP documents. I hate the language, but it was the first language I could actually learn from its own documentation.

For better or worse, I'm convinced that this is the reason that PHP took off the way it did. The documentation was clear, concise, easy to access (perhaps the first example of user friendly URLs I can remember), and effective; That each function had user-submitted (moderated) comments was the icing on the cake.

I've seen this (similarly highly-voted) comment made elsewhere. I just don't get it.

The PHP docs are often woefully incomplete in their explanation of functions. The user-submitted comments are the blind leading the lame, often containing competing solutions to the same problems, all of which are incomplete and poorly documented.

Aside from several highly-voted comments in discussions, though, the PHP documentation doesn't seem to be a frequently cited example of quality. I find that strange.

I seemed to be the only Python programmer who doesn't like its documentation page.

Programming tool that have the best documentation, to me, is jQuery. I think it's even better than php.net

> I have yet to see a language reference as good as the PHP documents.

Here you go:

http://www.lispworks.com/documentation/HyperSpec/Front/index...

Reply on news.ycombinator.com