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.

Some ideas worth mentioning:

Easy Navigation

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

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.

Last edited by shadow (2007-04-07 18:21:16)

Re: Rails Documentation Remix

To add to that, I think your design would have actually be complicated to intergrate into RDoc and I doubt Rails developers are going to want to do anything involving any additional effort.

Re: Rails Documentation Remix

LOL..yeah, my methods are indeed in the wrong place, i literally threw this together in 10 min.

Perhaps I am getting ahead of myself, but how hard could it be to customize the generator for rdocs to apply some CSS magic?

I would definitely be down to supply the front end code for this, I just dont know how much work it would take to fix those generators

Last edited by pimpmaster (2007-04-07 21:56:45)

Re: Rails Documentation Remix

Personally I think the standard api docs are very good as they are, that doesn't mean that there is no room for improvement.
A good idea in my opinion, do you intend to take it further?

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.

Stay tuned...

Re: Rails Documentation Remix

I see no reason why you couldn't send a quick e-mail to DHH and just point him at it. You never know he might do something about it (or delegate it to someone else).

Re: Rails Documentation Remix

Done!

Re: Rails Documentation Remix

Lets us know how it goes smile

10

Re: Rails Documentation Remix

They look much easier to use, the standard ones are a bit of a pain sometime when your looking for something but not sure where it is, live search is a good answer...

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.

Next stop, mailing list!

Re: Rails Documentation Remix

Yep - you could try the IRC channel too and see if anyone has any thoughts nt that?

Re: Rails Documentation Remix

Someone who complains of how the Rails documentation is laid out is someone who has never had the unfortunate need to use MSDN smile

But hey, improvements are always good. Go for it.

Re: Rails Documentation Remix

pimpmaster:  You're not alone in wanting better docs.  I used http://railsmanual.org (when it's not offline) because I can't stand the normal docs.

I would totally use your version.  Every day.

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.

I've written to both developers. More details to follow.

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.

Loren

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

Re: Rails Documentation Remix

I found aRails doc page that actually doesn't suck. I would probably still retool the look/feel,but I like how they have used AJAX and access keys to make thingsmuch snappier. Check it:

http://www.railsbrain.com/