The recent surge in documentation effort, spurred mainly by the Rails
Guides project, has caused the quality of Rails documentation to
improve greatly -- at least that's my humble opinion.
There still is a big hole in the online docs for Rails, though -- a
real, official, in-depth manual, akin to the ones offered by PHP and
Django.
The guides provide a great foundation for such a manual, essentially
being a chapter each (although editing and streamlining would be
necessary.)
Is there a strategy on this area? Should there be?
The guides as a whole are indeed intended to be the 'in depth'
introduction and tutorial for their areas of rails. With the rdoc
providing the detailed per class/method documentation. These two
needs are completely different and I think the improvement in both
these areas is enormous. They'll both, hopefully, continue to improve
as we go along.
What, beyond guides and rdoc, would a central manual be?
Both the guides and the rdoc live alongside the source, and are
maintained by the docrails guys:
The focus is really on building quality content at this point. There
is an unofficial #docrails channel on freenode, which is how we
usually communicate. So if you want to help out, you could drop by the
channel or shoot me an email.
I'm thinking about essentially having an online manual, complete with
instructions on how to install Rails, how to get started, and of
course guides to the different aspects of Rails.
I'm not suggesting that we take a radically different direction; just
that some of the existing, high-quality content would benefit from
being edited into a coherent manual, that can be read from start to
finish.
Furthermore, the reference documentation (rdoc) would benefit from
having links to the relevant chapters of such a manual.
I don't see any links from one site to the other? What's the purpose
of keeping them so seperate? It's nice having docs seperated out by
major versions on many sites, so you can actually go back to old docs
if you're working on an old project. Edge would be one of those
"versions" avaiable too. That's what I think would be useful doc
wise.
This is work-in-progress. We've had some light discussion of how to
version the external documentation going forward, but no plan in place
yet. Fortunately we don't have to settle that until 2.2 wraps and the
two sites start to diverge. We do plan to find some way to point
people at the distinction between the sites.
, only Rails 1.2 is covered. Many of the tutorials show
deprecated API's. Furthermore, these are all external tutorials, and
neither provide in-depth explanations that can match the quality of
e.g. Django.
The content's there -- why not attempt to edit it together? It doesn't
have to be right now, and I'm not saying that you guys should do it
(I'd be more than happy to help if there was agreement on a goal,) but
we really need a canonical, high-quality starting point for people
learning Rails.
I think the guides are great, but they are completely separate from
the other documentation.
I've recently helped a friend get started with Ruby and Rails, and my
observations of his experiences as a newcomer enticed me to begin this
thread.
Looking at the list of Rails tutorials at <http://rubyonrails.org/
>, only Rails 1.2 is covered. Many of the tutorials show
deprecated API's. Furthermore, these are all external tutorials, and
neither provide in-depth explanations that can match the quality of
e.g. Django.
This page will link to the guides once 2.2 is released. That's what
the guides were written to replace. We can't change that link now as
it references stuff which isn't in a shipping release.
The content's there -- why not attempt to edit it together? It doesn't
have to be right now, and I'm not saying that you guys should do it
(I'd be more than happy to help if there was agreement on a goal,) but
we really need a canonical, high-quality starting point for people
learning Rails.
What you're talking about is a 'getting started with rails' guide
which covers the basics and links off to other guides / rdoc for more
detail:
Suggestions for improvement can be added in the lighthouse ticket, but
ideally that will be the one place where new programmers can start,
and it will point them to everything else they need to know.
Okay, i guess that's as good as it can get then -- there will be links
to that from rubyonrails.org, hopefully?
Absolutely, the only reason they're not there now is that the guides
document 2.2, not 2.1 and that's likely to be just as confusing as
the current situation.
