This page is part of the ongoing DocumentationDiscussion p{border:1px solid green;padding: 0.5em;}. WikiGardening required. This document was (roughtly) cut out of DocumentationDiscussion and could use a good scrubing down. What is wrong/missing/could-be-improved, what we would like to have. h2. What "PHP Documentation":http://www.php.net/docs.php does well * Search (function list, whole site, online docs, bug db, etc) * Comments -- user contributed notes include useful snippets and idioms * URL shortcuts -- simple, guessable urls go to function or section references. eg. php.net/trim or php.net/strings * Sensible URLs (no frameset) * Excellent 404 behaviour (related to url shortcuts above). All 404s turn into doc searches. * good overall breakdown: ** Getting Started, Installation and Configuration, Language Reference, Security, Features, Function Reference, .. API .., FAQ: Frequently Asked Questions, Appendixes ** there is a mix of *subject specific* material (features, security, installation), *broad general* information (getting started, language reference) and *very specific* (function ref. and APIs) ** it is important to cover the very granular and the big-picture. Seasoned users will likely spend most of their time in the API reference, but new users need context, guidance, introductions. * The API/functions reference ** Divided into 'sections' ** 1 page per section ** 1 pager per function *** Function prototype, description, version info, example usage with input and output h2. Beefs with RDoc * URLs change (I think), at least the #achor portions) * Documentation is structured around file and module organization, which is hard to use if you're not already familiar with the structure and organization of the framework. * No search * a frameset !? * contains only API details, not "manual style" content. Doesn't stitch the pieces together, just enumerates all the different parts. This creates challenges for new users, since they don't know where to begin. We need some content that relates to generic concepts (like sessions for example) that explain how they work _in Rails_ and points to the API references. Many of the READMEs contain this sort of info, but are too brief to be the last word on the matter. h2. \RoRDoc should have * Search (maybe try "gonzui":http://gonzui.sourceforge.net/ ?) * 1 page per method, module/class * Sensible, persistant urls ** How do you map nested modules into a nice, un-nested url? * Ability to import in some automated fashion ** RDoc xml? * An extensible XML API that allows anyone to tap into the core information of the doc, and transform it to their liking ** Would allow HTML & PDF Versions updated dynamically via XSLT ** Would allow others to tinker with the UI on their own machines. * allow user comments * single file PDF(portable document format) downloadable/printable version. (There was some "discussion":http://one.textdrive.com/pipermail/rails/2005-March/thread.html#4372 on the mailinglist recently about this as well, but the above sums it up pretty good.) h3. User Contributions PHP.net's comments are at times more useful than the docs proper. We need to look at * what we can do to faclitate user contribution * how we can or need to moderate user submissions * what shape these user contributions have (comments? wiki? threaded? ** What about if each page has the official docs, then a wiki content section, followed user comments/discussion at the bottom of the page. ** *LeeO:* I think having both wiki and user comments is a little redundant. Xal suggested exposing the rdoc code as editable through a wiki like interface(as well, he suggested that the changes could then be auto-submitted to the issue tracker, but xal is a little crazy!). * how we can leverage exising resources (eg this wiki) and foster cross-referencing between the api docs & wiki / other resources where appropriate * user accounts? how do we handle / foster cross-linking to & from the rails docs & wiki? h3. What do we need? # A plan! #* What are the requirements? #* What is the scope? #* What should the models look like? #* are we building a framework for all ruby documentation, or just for rails (am I getting ahead of myself? We can always extract later, I guess. -- LeeO) # What does the UI look like? #* URL UI, especially nested modules, dealing with abiguous names. #* how to deal with the fact that Rails is composed of seperate(and potentially standalone) modules? #** *LeeO:* While the module as subdomain works on a certain level, I don't think the division is logical to Rails newcommers. I think most people are predominantly interested in using Rails as a whole unit, with much less interest in using individual components in standalone situations. *Turing:* I agree with this - I just found all the ViewHelpers in the API docs, I somehow skipped over them on my initial reading - I would never have missed something so important in the PHP Docs because of their (excellent) layout. #** I'd like the following URLs to work -- they should get the user to the right place, they do not represent the actual final URIs. #*** doc.rubyonrails.com/has_one #*** doc.rubyonrails.com/actionview -- Would be nice to also have some shortcuts, like av -> actionview. #*** doc.rubyonrails.com/time_zone.rb #** urls should be case-insensitive, and flexible, eg. ommiting ".rb" from a filename, or redirecting to module/base when "base" ommited. #* LeeO: I've thrown together a mockup of what a method page might look like http://www.omara.ca/rails/rordoc/mockup3.png *Turing:* That looks excellent - I would also propose to have an easily-printable html version or a straight PDF download with bookmarks. h3. Questions for developers/higher-ups * Doc sources ** Should rdoc be the primary/sole source of documentation. *Turing:* absolutely no no no. :) ** Does this include non-api documentation? * Subdomains ** is it important to maintain the subdomains for seperate docs? *** A single docs.rubyonrails.com will likely be the most straightforward and 'authoritative' place to find everything. * Release ** Revision name/version are to be manually entered. Is there another way? * Previous versions ** Is keeping back-versions important? That is, keeping documentation of previous releases? *Turing:* PHP does this very well. It warns of specific bahavior in various versions, and provides information on when some package or function came into existance. It's excellent. There _will_ be projects that require a specific rails version, most likely because of changes to AR that break backward compatibility. *** Multiple versions should be supported. For instance, when Rails 2.0 comes out there will additions and may be some (likely minimal) breakage. Since people will have different versions installed and not always be able to run the newest version, in the long term it needs to have this ability.