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.
- RorDocErrors A page to put all errors in the current api docs, or any other doc place.
The Rails Documentation Project members:
Please add your name to the list if you wish to contribute.
- cdcarter Chris Carter (starting to do lots of work with docs.)
- LeeO
- JohanSorensen
- BenStiglitz (I can probably donate some time at work)
- DaveLee (I think I can help with the steering & ideas; we’ll see about the implementation)
- GavinSinclair (see my user page for comments on Rails documentation)
- ColinRamsay
- DuaneJohnson (desperate for searchable docs, came up with RailDock)
- pixelmartini
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/