This page is part of the ongoing DocumentationDiscussion

p{border:1px solid green;padding: 0.5em;}. WikiGardening required.  This document could use a good scrubbing down.

We should consider the UI exposed to different RorDocUsers (since the requirements/tasks of a user will be quite different than those of a RoR developer, or documentation maintainer)

h2. Interface features/considerations

* Search (function list, whole site, online docs, bug db, etc)
** LeeO: I have added a simple search to "this frameset":http://omara.ca/rails that directs to either a google search of the API or a wiki search.
** ColinRamsay: I've got a very basic bookmarklet to search the docs via Google. "Take a look.":http://colinramsay.co.uk/diary/archives/000163.html
* allow user comments
* Comments -- user contributed notes include useful snippets and idioms (not a place to report bugs or ask questions)
* Maybe we should look at the navigation. The recent layout change to the frameset made the content much more accessible with minimum effort. The "alternative layout here":http://www.omara.ca/rails/ is arguably even more usable.
** possibly a different class navigation method; a collapsible tree for browsing classes ? 
* lose the FILES window?
* NO FRAMES
* LeeO: I've thrown together a mockup of what a method page might look like http://www.omara.ca/rails/rordoc/mockup3.png


h2. URL interface

* Sensible, persistant urls(aka NiceLinks). Easy to bookmark or guess (no frameset)
** How do you map nested modules into a nice, un-nested url?
* URL shortcuts -- simple, guessable urls go to function or section references. eg. domain/trim or domain/strings
** see everything that PHP net does: http://www.php.net/urlhowto.php
* 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 hortcuts, like av -> actionview.
** doc.rubyonrails.com/time_zone.rb
* urls should be case-insensitive, and flexible, eg. ommiting ".rb" rom a filename, or redirecting to module/base when "base" ommited.
* nested modules - how to deal 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.
* Excellent 404 behaviour (related to url shortcuts above). All 404s turn into doc searches.


h2. User Interfaces: Encouraging (the right kind of) Interactions

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? 
** How can we ensure that comments are valuable/accurate? If we don't use a wiki we might need people to review the comments.
*** *LeeO:* I don't think it unreasonable to have moderators to review/moderate comments
** 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?


h2. Content organization

* PHP shows a good range and organization of content:
**  Getting Started, Installation and Configuration, Language Reference, Security, Features, Function Reference, .. API .., FAQ, Appendixes
** there is a mix of *subject specific* material (features, security, installation), *broad general* information (getting started, language reference) and *content 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
** 1 page per method, module/class
*** Function prototype, description, version info, example usage with input and output


h2. Questions for developers/higher-ups

* *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.
* *Previous versions:* Is keeping back-versions important? That is, keeping documentation of previous releases?
** 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.