Ricks point is also important - how we do it isn't _that_ important
(even though I'd say a forum isn't the way to go), the important thing
is that we're a group of people that agrees on something.
So, say that Rails is to get an official documentation team. Whose
decision would that be? DHH? Anyone in the core team? It would be nice
with an opinion from the person/people that can actually decide wether
or not to get an official team running.
I think he’s looking for official support. And I think he’s right in that yet another third party documentation effort isn’t what is required to solve the issues he’s mentioned. The documentation effort needs to be official in order to gain wide traction and to be seen as the one go-to-place for help. Rails already has documentation spread across thousands of articles all over the net, increasing the amount of dispersed documentation does not help one little bit.
That doesn’t mean that the current core team needs to do the documenting, only that some people committed to churning out great documentation need to do so with official blessing and sanctioning, on the official Rails webpage.
Because of the reasons mentioned above. An API is a reference tool,
and has a tremendously steep learning curve if you don't know anything
about Rails. The API is indeed documentation, but it's not sufficient
for a beginner. So, the official documentation is no good for
beginners. That's my main concern.
Because it's $30-40? I always hated the fact that to really get into
Rails I had to shell out for a book. Every time I looked for
narrative documentation of any sort, I was always pointed to a random
blog or the book (usually the latter). It actually sort of instilled
this weird, totally unfounded distrust of DHH in me for a while
because his name was on the cover, so it seemed like a ploy to make
money. Stupid? Yes. Uncommon? I don't think so.
All that's to say: I think it's dumb to have to spend a decent sum of
money to really be able to use Rails.
It's out of date and not a lot of content at this point, but I'd love
to get a group of people working around that to get it into shape.
Maintenance wouldn't be horrible if we tried to keep up with the major
Rails releases (1.1, 1.2, 2.0, etc., not 2.0.1 necessarily). It's
written in Markdown so far, so it shouldn't be horrible to get a lot
of people working on it.
Anyone interested in working on that or making concerted efforts on
the API docs (or anything else)? Ping me off list, on IRC (in
#rails-doc), or find me at a conference. I've got a Basecamp,
Lighthouse, blah blah blah to coordinate all the efforts.
The Django book is interesting, but (a) it was written by the creators
of Django and (b) it hasn't been updated in some time because they are
working on the dead tree version or something (which is actually out
of date before it even hit the shelf heh).
I loved the model though; the way they set the site up was awesome.
Because it's $30-40? I always hated the fact that to really get into
Rails I had to shell out for a book.
[snip]
All that's to say: I think it's dumb to have to spend a decent sum of
money to really be able to use Rails.
I totally sympathize, but actually i've only learned from books my
entire career. I've never really been about to use "official" docs
for much more than reference. That's been true since I first learned
BASIC, then Pascal, then C++, then .NET, now Ruby. I'm usually glad
to spend $100 on books for something new, because it pays itself back.
I think the reason that official docs are not as good is apparent. As
I'm sure you know, being a good writer is different than being a good
developer. That's why I've always found it odd that there are all
these appeals for developers to help write documentation. Developers
can maybe write reference material or rdoc-style docs. They can't
necessarily teach or explain well. In the same way that most Rails
programmers are also not good web designers.
It's out of date and not a lot of content at this point
[snip]
Exactly my point. Unless there are people who love to write, are
good at writing, and get some kind of reward (monetary, recognition,
or otherwise), this is doomed to happen. It's no one's fault, it's
just how it is. Some developers are good at it (like you), most are
not. Look at the Rails blogosphere. The good ones tend to be by
developers who also write well and teach well. And that's why it's
also hard to have a successful technical blog.
I wouldn't normally jump into a rails-core discussion, but what I'm
working on seems relevant to this thread.
My colleague Christopher Haupt and I are deep into building a portal
site to serve Ruby on Rails developers at www.BuildingWebApps.com.
We're going to be providing annotated links to all the key content on
the web related to Rails, and we'll have quite a few of our own
articles as well. We'd be thrilled to work with the core team to make
this as helpful for the community as it can be.
We're also started the LearningRails podcast (www.LearningRails.com),
which I think will be a great resource for people new to the platform,
especially if they come from a traditional web background rather than
a computer science background.
One distinction that tends to get muddled in these discussions is that
between documentation and tutorials. The Rails API documents are fine
as far as they go, but they are API documentation, not tutorials, and
they should not be expected to be the way new users learn the
platform. (That said, they could use a little more explanatory text in
many cases.) Tutorials are a different beast. (Obie Fernandez's new
The Rails Way book, which is really outstanding by the way, is
interesting because it sits more on the fence than other works: it is
both documentation and tutorial.)
We'll be creating a lot of tutorial content, but will be pointing to
other places for documentation.
Michael Slater
www.BuildingWebApps.com
P.S. In case you're wondering if this is another flash-in-the-pan site
that will fade once the developers find more paying work, don't worry.
This is a real business venture with (a little) funding and a (small)
dedicated staff. How can we do this when all the content is free?
We're offering seminars, which will be money-makers, and eventually
we'll have some premium content (such as video tutorials). And the
bigger picture here is that we're building a platform to organize the
knowledge of any community. We're starting with the Rails community
because it's the one we're part of and one for which we see big
opportunities to make a contribution. But our long-term business plan
is to make money by offering our platform for other knowledge domains.
Honestly, I don't think we need to go out and create another
documentation project. There have been many and to me that is the
problem. If those who want to be part of documenting rails could come
together as one and work as a team (documentation core team or what have
you), that would be awesome.
The same story keeps being retold: "I started a documentation project,
asked for help, after such and such time, received none and the site
went dark". Something to think about there.
My suggestion would be to pull together and work on Jeremy's already
existing project, instead of going out and trying to, again, create a
doc project. Also, we could just write our own app for handling the
documentation project, providing such features as the django book or
what not. With pdf-writer, it'd be easy to spit out pdf versions of
chapters or the whole book.
I'd rather see, and perhaps be part of, something like this than see
another doc project created and hear later on that it too failed because
no one joined it (instead they went out and created their own).
> I'd like to throw in, though, that although Rails has pretty good
> resources for many topics, they are really hard to find sometimes when
> you don't exactly know what to search for.
You go to google, type in "ruby on rails", click on "documentation"
and voila:
I think this lists a good number of resources to get you started.
Manfred, that page is a mess, with links that don't work,
documentation more than 2 years old and references to sites (howtos
and manuals) that are incomplete or a complete mess. It's absolutely
impossible to know if any of the howtos are even relevant anymore
because there are no dates on anything and like August said, one of
the first manuals is how to migrate to rails 1.0?!
On top of that, the really usefull documentation is scattered around
hundreds of different blogs which are extremely difficult to find
unless you know exactly what you're looking for. It's almost as if
finding documentation is the initiation you go through in order to
have the priviledge of using rails. We're moving on to rails 2.0 with
new conventions and new ways of doing things and yet new developers
are going to start from the pre-1.0 days and progress to rails 2.0 as
they stumble upon information.
How is a new developer supposed to know that REST is the current
convention, or even explain why rails chose REST? I only found this
out because I just happened to watch DHH's keynote at the 2006
railsconf. What about plugins that are outdated
(acts_as_authenticated or login_generator)? Or what different
pagination plugins are offered and how they're different, etc.
There's just no way the current documentation situation is adequate.
I feel like the Rails wiki plus Jeremy's project could help a lot of this.
But - let's be honest - the Rails wiki is just utterly useless. I can't
remember the last time I even bothered looking at it before (or after)
Googling - or even debugging.
I'm gonna make another in a series of unpopular suggestions:
MediaWiki.
Now, keep in mind: I hate MediaWiki. I hate its syntax, I hate its feel, I
hate its complexity. I hate that it's not written in Ruby.
But you know what? Wikipedia's freaking awesome. And whatever it needs,
MediaWiki has.
It's got despamming, it's got authentication, it's got terrific history
tools, fancy templates, etc. etc. There's a syntax-highlighting plugin for
it, too. There's even a Textile plugin. And the article/talk page
dichotomy would solve one big problem of the Rails wiki.
Wikis are particularly handy because - at least from my POV - you spend
huge amounts of time on a problem or question when you're working your way
through it, and then you never think about it again. That's why we have
all these beginners asking the same questions, and all the experts
wondering why people keep asking. Wikis are a very handy way of working on
a problem while you're thinking about it, and organizing your thoughts
later.
MediaWiki has two additional benefits: Huge numbers of people are already
familiar with how to use it (thanks to Wikipedia), and there are a bunch of
automated tools that work with it.
What would it take for rails-core to even consider such a thing?
I just wonder how much of Wikipedia's usefulness is due to the
software, and how much is due to the community that keeps everything
tidy. At any rate, I think mediawiki's worth a shot. Go for it.
I just wonder how much of Wikipedia's usefulness is due to the
software, and how much is due to the community that keeps everything
tidy.
Oh,a huge part of it's the community, definitely. Like any large,
general-purpose community, Wikipedia's grown its own set of Neighborhood
Watch types... which is sometimes good, and sometimes bad!
I just meant that sometimes it's better to grab something off the shelf
where you know you're NOT the most demanding customer on the bleeding edge.
Even if you CAN do better rolling your own, doesn't mean you will, or that
it's the best use of your time.. my list of "programs I'm not buying/using
because I know I can write something better" has topped off at about 50
these days..
At any rate, I think mediawiki's worth a shot. Go for it.
Oh, I will, Rick Olson. I will indeed.
Er, I mean, anyone know where I can get a DB dump of the i2 wiki?
Because of the reasons mentioned above. An API is a reference tool,
and has a tremendously steep learning curve if you don't know anything
about Rails. The API is indeed documentation, but it's not sufficient
for a beginner. So, the official documentation is no good for
beginners. That's my main concern.
On Dec 14, 2:51 pm, Thijs van der Vossen <t.vandervos...@gmail.com>
August,
I agree that a core doc team is an excellent idea. But it's also great
that other sites would provide this too. That would mean that people
could go to whatever site they find more easily(they are n00b's after
all ) or like better. Plus content could be copied back and forth if
it was worthwhile and fit both styles. www.rubyonrails/docs is the
probably the first place people look, and pointing at an API does look
really bad. Maybe, starting something on that railsbeginner domain and
hoping to get it moved to rails/docs(/beginner ?) or linked to from
there would be a good way to get people interested. Especially as this
has been a fairly well received post. PM once you know what you are
doing with improving documentation. I'd like to get involved.
My colleague Christopher Haupt and I are deep into building a portal
site to serve Ruby on Rails developers at www.BuildingWebApps.com.
We're going to be providing annotated links to all the key content on
the web related to Rails, and we'll have quite a few of our own
articles as well. We'd be thrilled to work with the core team to make
this as helpful for the community as it can be.
We're also started the LearningRails podcast (www.LearningRails.com),
which I think will be a great resource for people new to the platform,
especially if they come from a traditional web background rather than
a computer science background.
This looks pretty good. I saw the other thing on lighthouse:
http://railsdocs.lighthouseapp.com/projects/2637
They've got a pretty good book together there. And there's a decent
amount of stuff on the rails wiki too. It just looks like this stuff
needs to be assembled into one official site on rubyonrails.org. A good
core doc team could not only do this, but also keep it up to date as new
stuff happens. And fill in obscure things that are only in blogs. I also
think that documenting the more popular plugins might be in our interest
if the developers of those aren't doing it.