Posts [ 20 ]

Topic: Rails Documentation Remix

I dont know about you guys, but personally I think the standard Rails documentation leaves much to be desired. The blue header, the vanilla code examples... the whole iframes thing. You can tell it was designed by a programmer... which is not bad in and of itself, but as a designer I feel the CSS and overall GUI needs some love.

I have roughed up a few comps and would be interested in your feedback.

Re: Rails Documentation Remix

If your being 37s you need a bigger blue gradient at the top and I'm not sure why you have ActionController classes stuff under Active Record.

But in all seriousness, its looks good, hopefully someone will actually do something with that. I'm a regular visitor to the Rails API docs and use Firefox's built-in find to find whatever I need and that does the job well enough.

The new(ish) prototype API doc is excellent as a point of reference.

As a designer myself, I completely agree with everything you say about the existing design.

Re: Rails Documentation Remix

techjournal,

Unfortunately I am still pretty new to Ruby and am not sure how to manipulate the rdoc generators to spit out the desired content. I have already started building the HTML/CSS for this project and will post it here in and in other forums in hopes that a developer (who is savvier than me) will be able to tweak rdoc appropriately.

Re: Rails Documentation Remix

UPDATE: DHH found about 3 seconds of free time to hit me back

Nice work. I think part of the problem with dull API looks is that rdoc templates aren't terribly customizable at this point. I would post this to the mailing list and see if there are someone there who could help you turn it into rdoc or even extend rdoc were needed. Good luck.

It's cool he actually wrote me back, being the busy guy tat he is. But this quest is far from over.

Re: Rails Documentation Remix

Thanks for the encouragement, yall.

Looks like I got a good response from JeremyMcAnally (one of the good lads on the caboo.se project). It probably won't happen for months, but I definitely think this project would be well worth the effort.

Re: Rails Documentation Remix

UPDATE:

It turns out that I am not alone in my frustrations with rdoc. Apparently some folks think it needs to be scrapped completely and a fresh start is necessary. Some very interesting ideas are getting tossed around here and here.

Re: Rails Documentation Remix

Hi,

I run the YARD project (http://yard.soen.ca) that pimpmaster mentioned above. It's great to see interest in documentation, something Ruby can really use a hand in.

YARD is a project that really does extend far beyond just Rails, since, as some people mentioned, Rails docs are relatively "decent" (I wouldn't go as far as "very good" though) compared to regular Ruby docs.

That said, I'm a Rails developer myself, and improving Rails docs was definitely one of the motivations of this project. A lot of the improvement that you may be seeking (and a lot of other people too), as shadow mentioned, cannot be done with RDoc. Inherited methods, constants, and other such information isn't easily available with current documentation. That's where YARD comes in.

YARD is designed to be extensible from the start. This means that it works great with Ruby DSLs like Rails. It becomes very easy (only a few lines of code under the domain logic) with YARD to give meaning to statements such as "has_many", "belongs_to", "validates_uniqueness_of", or others; this is something that few people have even thought of achieving through Rails documentation improvement because of the current limitations of RDoc. This may not help Rails core documentation too much, but it would aid third party plugin and application level documentation immensely.

YARD also stores all of its parsed data in a 'raw' format; this means that generating XHTML/CSS isn't a necessary step. You can easily take the database that YARD generates and export it to an SQL database for use in an online/interactive webapp that could support user comments, live search, etc. YARD generates HTML with a template framework the same way Rails does (eruby), so this means you can add your own stylesheets/templates and literally change the way documentation displays from top to bottom, making your above mockup perfectly feasible and rather simple with YARD. You're also given a lot more freedom with what information you want to work with.

YARD is fully compatible with RDoc style documentation syntax, but also adds extra functionality to consistently describe argument parameters, required types (when types or duck-types are relevant), exceptions that are raised, and other things. While Yardoc syntax would require *changing* the Rails documentation, hopefully if YARD becomes embraced by the community, everyone will be able to reap the benefits of better, more consistent docs in terms of content, not just presentation.

Anyway, I like your ideas pimpmaster, and your mockup looks nice. I would recommend the following:

* Look into providing more content to documentation pages. Method inheritance might be nice, so would class inheritance trees. Most of the problems with Rails docs aren't based on presentation, but the missing content that it fails to provide; ask yourself if that can be improved in an unintrusive fashion. What methods raise exceptions? In many cases, YARD can provide this information even if the developer did not.

* Is organization by "File" really all that necessary? Most developers don't (and shouldn't) know the internal ActiveRecord/Support/Controller directory/file structures, and probably don't care. Perhaps make it available but in another form.

* I haven't seen your listing of methods, but I would immediately suggest not organizing method names alphabetically, but contextually.. possibly under proper headings. Remember that there are many methods named "new" in the current API docs and that's one of the problems I have in sifting through methods on the current pages.

Anyway, I hope all of this gives you an idea on what my project YARD is about, and what it can bring to the table both for the Rails community and the rest of the Ruby world. Without tooting my own horn too much, I encourage all of you to check out the site and play around with it (I recommend checking the project out from the trunk SVN repo, the gem is a bit out of date) to see what you can do. The site is also a bit out of date, hopefully I will have time to update it soon.

Re: Rails Documentation Remix

This looks really interesting. I downloaded from trunk and I must admit a lot of this is way over my head. I think I need to become more fluent with Rails and Ruby before I can really collaborate on something like this. For now I will stick to JPEG comps and post up an official site where people can check it out and post feedback.

Re: Rails Documentation Remix

I was reading this the other day and I don't know why I didn't think of this but you guys might want to try - gotAPI.com

It doesn't have all of the features listed above but it's really easy to look stuff up. Plus it has a ton of APIs to search including HTML, CSS, PROTOTYPE, jQuery, MySQL, Rails, Ruby, Ruby Standard Packages, and RMagic