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 school. Theme #2 - Shiny: Style that is consistent with 37 Signals and RoR Brand. <img src="http://www.funkysoulrebels.com/rails/Yang.jpg" /> Theme #3 - Twilight: Inverted scheme for those of us who prefer dark screens and light text. (see attachment) <img src="http://www.funkysoulrebels.com/rails/Yin.jpg" /> 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. --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Ruby on Rails: Talk" group. To post to this group, send email to rubyonrails-talk-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org To unsubscribe from this group, send email to rubyonrails-talk-unsubscribe@googlegroups.com For more options, visit this group at http://groups.google.com/group/rubyonrails-talk?hl=en -~----------~----~----~----~------~----~------~--~---
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 goals... --Jeremy On 4/16/07, pimpmaster <stevendgarcia-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:> > 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 > school. > Theme #2 - Shiny: Style that is consistent with 37 Signals and RoR > Brand. > <img src="http://www.funkysoulrebels.com/rails/Yang.jpg" /> > Theme #3 - Twilight: Inverted scheme for those of us who prefer dark > screens and light text. (see attachment) > <img src="http://www.funkysoulrebels.com/rails/Yin.jpg" /> > > 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. > > > > >-- http://www.jeremymcanally.com/ My free Ruby e-book: http://www.humblelittlerubybook.com/book/ My blogs: http://www.mrneighborly.com/ http://www.rubyinpractice.com/ --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Ruby on Rails: Talk" group. To post to this group, send email to rubyonrails-talk-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org To unsubscribe from this group, send email to rubyonrails-talk-unsubscribe@googlegroups.com For more options, visit this group at http://groups.google.com/group/rubyonrails-talk?hl=en -~----------~----~----~----~------~----~------~--~---
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 ;-) --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Ruby on Rails: Talk" group. To post to this group, send email to rubyonrails-talk-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org To unsubscribe from this group, send email to rubyonrails-talk-unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org For more options, visit this group at http://groups.google.com/group/rubyonrails-talk?hl=en -~----------~----~----~----~------~----~------~--~---
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 (http://arti-ar.cfcl.com) overview page covers some complimentary topics:> As a dynamic programming language, Ruby is not an easy target > for documentation generators. Almost any part of a Ruby program > can be (re)defined at run time, so static code analysis may fail > to gather critical information. Systems such as Rails, which > make extensive and intricate use of Ruby''s dynamic capabilities, > are particularly hard to analyze. > > RDoc, designed by Dave Thomas, is the de facto standard for Ruby > documentation tools. It analyzes Ruby source code and collects > embedded comments, generating a structured collection of pages > for Ruby files, objects, and methods. RDoc is included as part > of the Ruby core distribution; commands to use it (e.g., > "rake doc:app") are built into Rails. > > Nonetheless, the RDoc support in Rails is not very extensive, let > alone well integrated into the toolkit. Only the application > code is analyzed; libraries (whether for Rails or other Ruby > topics) are not documented by default. Also, RDoc takes no > advantage of the extremely regular structure and naming conventions > of Rails. So, it knows nothing about actions, environments, > controllers, helpers, layouts, models, partials, tests, views, etc. > > The Ruby support could also use improvement. Although syntax > coloring is provided for the source code snippets, no support is > provided for linking from (say) method calls to their definitions. > Nor, by default, can the full source code of the application be > perused through the RDoc interface. > > Finally, because RDoc''s design and implementation predate Rails, > it generates static web pages that cannot be browsed through Rails, > let alone take advantage of Rails'' dynamic capabilities. Although> > RDoc has taken us a long way, it is clearly time to put in some more > 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 (http://www.soen.ca), 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. -r -- http://www.cfcl.com/rdm Rich Morin http://www.cfcl.com/rdm/resume rdm-go8te9J4rpw@public.gmane.org http://www.cfcl.com/rdm/weblog +1 650-873-7841 Technical editing and writing, programming, and web development --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Ruby on Rails: Talk" group. To post to this group, send email to rubyonrails-talk-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org To unsubscribe from this group, send email to rubyonrails-talk-unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org For more options, visit this group at http://groups.google.com/group/rubyonrails-talk?hl=en -~----------~----~----~----~------~----~------~--~---
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 ActionController ActionController::AbstractRequest ActionController::Assertions::DomAssertions ActionController::Assertions::ModelAssertions ... with ActionController | 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... -r -- http://www.cfcl.com/rdm Rich Morin http://www.cfcl.com/rdm/resume rdm-go8te9J4rpw@public.gmane.org http://www.cfcl.com/rdm/weblog +1 650-873-7841 Technical editing and writing, programming, and web development --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Ruby on Rails: Talk" group. To post to this group, send email to rubyonrails-talk-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org To unsubscribe from this group, send email to rubyonrails-talk-unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org For more options, visit this group at http://groups.google.com/group/rubyonrails-talk?hl=en -~----------~----~----~----~------~----~------~--~---
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 --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Ruby on Rails: Talk" group. To post to this group, send email to rubyonrails-talk-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org To unsubscribe from this group, send email to rubyonrails-talk-unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org For more options, visit this group at http://groups.google.com/group/rubyonrails-talk?hl=en -~----------~----~----~----~------~----~------~--~---