Ruby on Rails
DocumentationDiscussion (Version #32)

Please use this page for constructive criticism and suggestions for improving Rails documentation. This is not limited to the current documentation (ie. the manuals(hieraki) and rdoc-genrated API docs).

This discussion has somewhat splintered, pieces can be here and on The ‘Middle’ Documentation Problem. ManualDiscussion and ProblemBaseDiscussion are worthwhile reads, as is HomePageDiscussion, to a certain extent.

Overview

  • RorDocGoals — What is wrong/missing/could-be-improved, what we would like to have.
  • RorDocUI — Encouraging (the right kind of) Interactions
  • RorDocContent — what is already available, how can it be used/organized, plus bending RDoc to our will
  • RorDocUsingHieraki
  • RorDocPlans
  • RorDocUsers — who will need to use the system, and what are their requirements/goals/tasks.

The Rails Documentation Project members:

Please add your name to the list if you wish to contribute.

Bugs in Current Docs

The pre {} rule in /stylesheets/more.css prevents (at least) the testing tutorial from printing from either IE or Firefox on \WinXP. (Both mangle the printed form differently; IE overlays non-pre text over the example code; Firefox loses chunks of text.) Commenting out the overflow: in the pre {} rule resolves the problem. —DaveSmith

Warning: The stylesheet http://wiki.rubyonrails.com/rails/static_style_sheet/ was
loaded as CSS even though its MIME type “text/html”, is not “text/css”. — MarkusQ

Idea Bin

There are some good ideas (which were lost in a recent rollback) that came up on IRC. See xal’s comments on around here http://www.loglibrary.com/show_page/view/62?EndTime=1112121192&StartTime=1112120852

In the meantime

  • LeeO: I have added a simple search to this frameset that allows you to search the API with google or search the wiki.
  • ColinRamsay: I’m working on a bookmarklet to allow a search of the docs. Have a look here.
  • experimenting with rdoc
    rdoc -fhtml —one-file > doc.html
    generates one large html file, but it doesn’t have the methods. More poking required.
  • Acrobat can suck down the Whole Thing. Frames look awfull. Code snippets wrap(because they can’t very well scroll can they) and the text is just way to big. Also, all those “[show source]” links look pretty silly. On the upside, internal links work, for the most part.
  • RailDock is a quick hack to combine the resources of rdoc’s RI classes with RubyOdeum? (text search). I (DuaneJohnson) haven’t spent as much time as you all have on the good questions and problems that have been raised on these wiki pages, but I’m willing to chip in if I can.
  • Annotated documentation is also available at http://rails.outertrack.com/

Please use this page for constructive criticism and suggestions for improving Rails documentation. This is not limited to the current documentation (ie. the manuals(hieraki) and rdoc-genrated API docs).

This discussion has somewhat splintered, pieces can be here and on The ‘Middle’ Documentation Problem. ManualDiscussion and ProblemBaseDiscussion are worthwhile reads, as is HomePageDiscussion, to a certain extent.

Overview

  • RorDocGoals — What is wrong/missing/could-be-improved, what we would like to have.
  • RorDocUI — Encouraging (the right kind of) Interactions
  • RorDocContent — what is already available, how can it be used/organized, plus bending RDoc to our will
  • RorDocUsingHieraki
  • RorDocPlans
  • RorDocUsers — who will need to use the system, and what are their requirements/goals/tasks.

The Rails Documentation Project members:

Please add your name to the list if you wish to contribute.

Bugs in Current Docs

The pre {} rule in /stylesheets/more.css prevents (at least) the testing tutorial from printing from either IE or Firefox on \WinXP. (Both mangle the printed form differently; IE overlays non-pre text over the example code; Firefox loses chunks of text.) Commenting out the overflow: in the pre {} rule resolves the problem. —DaveSmith

Warning: The stylesheet http://wiki.rubyonrails.com/rails/static_style_sheet/ was
loaded as CSS even though its MIME type “text/html”, is not “text/css”. — MarkusQ

Idea Bin

There are some good ideas (which were lost in a recent rollback) that came up on IRC. See xal’s comments on around here http://www.loglibrary.com/show_page/view/62?EndTime=1112121192&StartTime=1112120852

In the meantime

  • LeeO: I have added a simple search to this frameset that allows you to search the API with google or search the wiki.
  • ColinRamsay: I’m working on a bookmarklet to allow a search of the docs. Have a look here.
  • experimenting with rdoc
    rdoc -fhtml —one-file > doc.html
    generates one large html file, but it doesn’t have the methods. More poking required.
  • Acrobat can suck down the Whole Thing. Frames look awfull. Code snippets wrap(because they can’t very well scroll can they) and the text is just way to big. Also, all those “[show source]” links look pretty silly. On the upside, internal links work, for the most part.
  • RailDock is a quick hack to combine the resources of rdoc’s RI classes with RubyOdeum? (text search). I (DuaneJohnson) haven’t spent as much time as you all have on the good questions and problems that have been raised on these wiki pages, but I’m willing to chip in if I can.
  • Annotated documentation is also available at http://rails.outertrack.com/