Forum: Ruby on Rails Plastic Surgery for RDOC

Announcement (2017-05-07): is now read-only since I unfortunately do not have the time to support and maintain the forum any more. Please see and for other Rails- und Ruby-related community platforms.
67c02d91e6570d0a0f6e67f96dd7ce28?d=identicon&s=25 pimpmaster (Guest)
on 2007-04-16 19:25
(Received via mailing list)
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.

Some ideas worth mentioning:

Easier Navigation

· Tabbed navigation using javascript tabs for fast switching.
· Use of access keys (1-5 for top row 6-8 for bottom row)
· Live Search via AJAX

Increased Readability

· Code snippets in color
· Clean, Legible Headers and heirarchy of data

CSS Style Switching

Theme #1 - Classic: Standard API style for those who like the old
Theme #2 - Shiny: Style that is consistent with 37 Signals and RoR
<img src="" />
Theme #3 - Twilight: Inverted scheme for those of us who prefer dark
screens and light text. (see attachment)
<img src="" />

The HTML/CSS for this is nothing I can'thandle.. the real challenge is
making rdoc spit out more customizeable code. I spoke to DHH about
this challenge and he really liked the ideas. His advice was to
connect with experienced Rubyists who would be willing to tackle the
inner workings of rdoc.

This post is my call-to-arms for any experienced programmers who would
be interested in giving the docs a well-deserved kick in the ass.

Any feedback/critiques are welcome.
6d3c187a8b3ef53b08e3e7e8572c4fea?d=identicon&s=25 Jeremy McAnally (Guest)
on 2007-04-16 21:17
(Received via mailing list)
I really REALLY like the "Yang" version.

For my Google Summer of Code project, I'm doing a documentation
coverage analyzer.  My mentor, Chad Fowler, and I are looking at what
we can do to refactor RDoc to make my project easier.  Maybe we could
figure out some nice refactoring work that would accomplish both


On 4/16/07, pimpmaster <> wrote:
> making rdoc spit out more customizeable code. I spoke to DHH about
> >


My free Ruby e-book:

My blogs:
67c02d91e6570d0a0f6e67f96dd7ce28?d=identicon&s=25 pimpmaster (Guest)
on 2007-04-16 23:28
(Received via mailing list)
That would rock so hardcore if you and Chad could figure this pickle
out. I am pretty busy these days, but the prospect of you two tackling
this has me stoked enough to start slicing up some GIFs and mapping
out my coding strategy (I like my html/css lean, mean and STRICT).

I will post my progress in this thread. As added motivation, I will be
coding the Yang scheme first ;-)
D4d28bd014f9e7324bad99dcc3b0d390?d=identicon&s=25 Rich Morin (Guest)
on 2007-04-17 01:44
(Received via mailing list)
At 10:23 AM -0700 4/16/07, pimpmaster wrote:
> ... the standard Rails documentation leaves much to be desired.

+1  However, I would submit that your critique and proposals do not
go nearly far enough.  The Arti ( overview
page covers some complimentary topics:

> for Ruby files, objects, and methods.  RDoc is included as part
> work on the problem.
So, Arti is clearly fishing in the same pond (and will happily take
advantage of any improvements that come along!).  The Arti overview
also mentions several other interesting technologies.  Many of these
use a "load, then introspect" strategy which can gather information
that is difficult for static analysis to gather.

YARD (, in particular, has an interesting take on
extensible data collection.  In summary, I applaud your efforts, but
hope that your efforts can benefit (and benefit from) other projects
in this space.

--            Rich Morin     +1 650-873-7841

Technical editing and writing, programming, and web development
D4d28bd014f9e7324bad99dcc3b0d390?d=identicon&s=25 Rich Morin (Guest)
on 2007-04-17 17:27
(Received via mailing list)
I finally (D'oh) looked at the Yin and Yang layouts.  I like
the general approach; here are some suggestions:

  *  For those of us who think that black backgrounds are a
     Bad Idea, neither Yin nor Yang wins.  You might want to
     allow separate control of both the overall coloring and
     the coloring of code snippets.

  *  In the "Files" tab, I'd like to have the ability to see
     the entire code for each file.  It might also be nice
     to add line numbering, disclosure triangles, etc.  Take
     a look at TextMate for ideas...

  *  I'm not a big fan of using up large amounts of space on
     repeated information.  So, I'd replace



       | AbstractRequest
       | Assertions
       | | DomAssertions
       | | ModelAssertions

     Again, disclosure triangles (and perhaps "more" links)
     could be used to shorten long lists.

Finally, please set up some web pages for ActiveDocs, so that
there's an "official" place to refer folks to...

--            Rich Morin     +1 650-873-7841

Technical editing and writing, programming, and web development
67c02d91e6570d0a0f6e67f96dd7ce28?d=identicon&s=25 pimpmaster (Guest)
on 2007-04-17 17:43
(Received via mailing list)
Great stuff!

I will be be clearing up my online storage a bit to make way for an
activedocs section shortly

This is precisely the feedback I was looking for.. thanks for taking
the time to post this
This topic is locked and can not be replied to.