Todos for this Wiki
- TDD vs IDD discussion (copy from ML to wiki page)
- Info about working with forms (from ML)
- Create UnderstandingRequestParameters (or similar; see Craig Duncan’s email on the ML of 2005-04-24)
Resources
Resources are links to Rails-related “resources”, generally code or ideas you can use, or enlightening commentaries, or whatever. I’m collecting them here as I find them and will think of a way to organise them later.
- 2005-04-26: Lookup table in Rails
Comments on Rails Documentation
A lot of ideas are discussed at DocumentationDiscussion. Rather than further pollute that space, I’ll lay out my thoughts here.
Current State of Rails Documentation
At the moment (April 2005), the API documentation is very commendable for an open source project. There are holes, but most methods are documented, and most important classes and modules have good overview documentation.
A testament to the strength of the API documentation is that many questions on mailing lists and IRC contain a link to a particular class/module within the API docs.
The hieraki-based manuals are excellent, and prove that the hieraki platform is effective at delivering this kind of material.
Tutorials are very good, but more are needed. The existing ones only scratch the surface of Rails.
The Wiki has a lot of helpful content in it, and has benefited from extensive gardening. The Howtos section is particularly excellent, and should be a model for further organisation.
There’s a Rails FAQ website somewhere, but it’s difficult to find using Google. The maintainer says it’s undergoing a rewrite and will have a stronger presence in future.
Finally, several Rails books are due for release in 2005. Nearly all publishers make sample chapters available on their websites along with various supporting items such as introductory articles (O’Reilly are particularly good at this). These should be referenced from the relevant areas of the wiki.
What Needs Improving?
- The API docs need to be completed and (in some areas) improved. This is the developers’ responsibility, although other people keen to see improvement should contribute patches. A search feature on the API docs would be useful as well.
- We would benefit from more hieraki-based manuals (essentially article-length documents by a single author). This is a volunteer effort.
- A tutorial taking the reader into the depths of a realistic Rails app would be very helpful. Perhaps one of the books to be released will fill this need.
- The wiki could do with more organisation, which I’ll deal with in detail below.
- The FAQ, if it comes back up and becomes well-known, would be a good resource if well maintained.
What Doesn’t Need Improving?
On DocumentationDiscussion, there’s a lot of analysis about RDoc, and how its supposed limitations might be overcome. I say “forget it”. RDoc does its job extremely well. If we need or want better Rails documentation (infrastructure and content), it’s not because RDoc is holding us back.
You can’t link to method definitions in the RDoc output, because the anchors are merely sequential numbers, but you can link to classes and modules. For instance, the URL for FormTagHelper is http://api.rubyonrails.com/classes/ActionView/Helpers/FormTagHelper.html, which is entirely predictable based on the full module name ActionView::Helpers::FormTagHelper.
I suggest that being able to link to classes and modules is sufficient for referencing purposes in email and IRC. Furthermore, such links shouldn’t even be necessary: just link to the base API doc page, and tell them which class/module to look at.
Also, RDoc should only be used for API documentation. The other formats are better suited to other kinds of documentation. The Wiki should be able to tie it all together, providing links to the API, to articles, to tutorials, and also providing some original content.
Suggestion: Wiki Organising
The Howtos section of the wiki is very good. What’s good about iit?
- It’s prominent on the home page.
- It’s divided into sections (e.g. HowtosInstallation, HowtosDevelopment, …)
- Each “howto” is its own wiki page with a “Howto” categorisation.
Much of the rest of the wiki is poorly organised, though; such is the chaotic nature of wikis.
I like the “What are…?” pages; more of these should be added.
I introduced the “manuals” section. This would be better titled “Understanding”, and perhaps even better just rolled into “What are…?”.
I need to go into more detail here, but in summary:
- Each page should pay its way, not be simply left lying around.
- Each piece of Rails documentation should have its own page with a consistent focus: is it a howto? an explanation (what are…)?, an example, or something else?
Conclusion: How Should Rails Documentation Look?
We should read a Rails book to get the big picture.
We should use tutorials to get a guided, hands-on introduction to Rails.
We should use the API docs as a reference for understanding a paricular class/module/method.
We should read the hieraki-based manuals to gain detailed understanding of a particular facet of Rails (testing, internationalisation, security, …).
We should search and browse the wiki to find Q&A, introductions to various topics, links to other resources, etc.