Rails core team - only development?

Rails 2.0 is out. It's an awesome achievement, and it has improved a
lot from it's 1.x state (I was about to list everything to make this
introduction look good, but we all know what 2.0 has to offer, so I
won't =P).

We have a core team, and a "not-so-core" team of regular committers.
We do not, however, have a documentation team. I think Rails has grown
big enough to deserve having that, and it also makes sense to have it.
This is what we have today:

The API: This is getting better and better, thanks to documentation
patches and various upgrades through out it's history. Also, the
caboo.se API contributions are awesome. The API is an API, though, and
not a sufficient resource for someone completely new to rails, and
even completely new to making webapps in general.

The manuals: The first thing that meets your eye when you browse
http://manuals.rubyonrails.org is "Upgrading to Rails 1.0". Need I say
more? ; )

Railscasts.com: Probably the most awesome beginner-ish (and free)
documentation Rails has. Clean code and good practices. However, this
is not a complete tutorial either, as it won't explain how belongs_to
works (which the API will explain, but the beginner doesn't even know
what belongs_to is, and will never find it there)

The books: The books are also great, but they'll get outdated soon-
ish, and aren't free.

So, I'm suggesting that a separate documentation team is set up. This
is my first idea for getting started with awesome documentation:

railsbeginner.com (I even registered the domain because I was so
extremely pleased with the idea \o/)

People post their questions here. The core documentation team (which
would be me (?) and [insert other members here]) would post an answer
to that question, and tag/categorize the question (where a tag
containing the version of rails this is regarding is important).
Perhaps also even edit the question itself, in case it was written
poorly.

The answer should be a _real_ answer. No external references. "Look
in agile web development with rails", or "read the api" aren't
allowed. The answer should be there, in it's full, with everything
needed to answer the question.

If someone posts a duplicate question, the doc team will remove the
post. A mail will be sent to the person asking the question, notifying
him that the question was a duplicate (but stating that it was only
removed because it was a duplicate - feel free to post more questions
bla bla).

Simple as that. Questions with answers, categorized and searchable.

That way, one will get real questions. Not just questions made up by
an author or whatever. And it will be ever expandable.

So, let's just get at it? I can't find any reason not to.

Also, perhaps railsbeginner.com is a stupid idea, as it limits it to
beginners only. http://questions.rubyonrails.org, anyone?

The API is an API, though, and
not a sufficient resource for someone completely new to rails, and

even completely new to making webapps in general.

Amen! How soon we forget the difficulty of starting out in a new field :slight_smile:

Right now we’ve got three main resources that help newbs learn Rails for free: the rubyonrails mailing list (bulgeoning now, perhaps past it’s usefulness), http://railsforum.com
(where 97% of the good answers are by Ryan Bates), and RailsCasts (created by Ryan Bates).

There used to be Rails Weenie, which worked almost exactly in the question/answer format you’re describing, but it seems to have gone the way of the wooly mammoth.

So I think you’re on to something but we need to be careful not to just create another resource. We web developers tend to think that any problem can be solved with a website :slight_smile:

::Jack Danger

That's a good point, really. There is no magic involved, even though
it usually seems a lot like it is, at least when you just got the
idea.

However, I do think there's some pretty good arguments for making a
new site. This question/answer thing might sound a lot like a forum,
only that this particular page won't look like a forum at all. There's
no categories and boards, and no duplicate posts - the mod team tags
stuff (the community might tag stuff as well, but the mod team needs
to be nazis to make sure things are tagged "properly") and deletes
duplicates. And because it's an "official" site - at least that's what
it should be imo - you can't just forward the problem and say "sorry,
cba to answer" - the goal should be to answer all questions (unless
the question is obviously dumb and breaking Rails conventions, like
accessing sessions in models etc).

This should ideally be a collection of pretty much all the questions
people might have. You might argue that we'll get tons of dupe posts,
and half the job will be to delete those. But isn't that OK anyway?
I'm a regular on #rubyonrails (IRC), and we're basically being google
for the people there. They don't know what to search for and stuff, so
we're interpreting their questions and giving them an api link or a
google query in 2/3 of the questions. So the deleting-dupe-and-
pointing-out-the-answer to dupe posters is sort a part of the service.

Repeating myself here, but oh well - forums and mailing lists has no
clean and awesome way of detecting dupes when you get past a certain
amount of posts. Like, if someone posted a question here one year ago,
I doubt anyone is arsed to find that. This is because there's probably
10% unanswered posts, a lot of duplicates going on, and a lot of posts
with 2-3 retarded answers. This is mostly due to not having nazi-
moderation on dupes and such. And it's not because users are too lazy
to search or anything, they simply don't know what (or how) to search
for.

So as far as I can see, this is a new concept. Not just for Rails, but
open source projects in general.

Anyway, new webapp or not, I hope this posting of mine would at least
get a doc team running. Can't see why not =)

Kind of like we've been trying to do over at
http://www.railsdocumentation.org/ to no avail? :wink:

It's very hard to get people excited about doing documentation (unless
you're offering $$$). Honestly, it's hard (it's very difficult to
step out your own frame of reference and think about to write docs for
beginners through Rails masters) and it's very time consuming (it's
probably one of the few things in Ruby development that has a "build
process," that is, edit the docs, run rake doc:rails, check your
output, fix things, repeat), and, on top of that, there's very little
glory in it (do you see a Rails 2.0 "documentation a day" blog series
like you do with all the new features? ;)).

I'd be really interested in helping assemble a group of people to work
steadily on the documentation. I've pulled in a few people and we've
made some contributions, but it's never been formal and it's never
been consistent. I setup a BC but it fell to disrepair. I have a
Lighthouse that we used to file tickets in that no one fixed. I'd
really like to get this stuff going since I have more than enough time
now to devote to something like that, but I simply haven't seen all
that much interest.

As for the Q&A site, that would be cool so long as people had the time
and gusto to manage it. It would be a job! (Look at the mailing list
and IRC channel; think about all that being channeled into a single
site that's supposed to moderated and managed...) I'd be willing to
help build it if I'm needed, but I'd (personally) rather devote my
time to generating reference documentation than managing a "live
resource" like that.

--Jeremy

Rick Olson wrote and ran precisely such a Q&A site over at railsweenie.com or
some such and it was very active for a while but I guess eventually went
dark. Maybe he'd be interested in passing the code off to you and dumping the
existing data if he still has it and thinks it is still relevant. Then it
could be put up at railsbeginner.com or railsdocumentation.com or what have
you.

marcel

Rick Olson wrote and ran precisely such a Q&A site over at railsweenie.com or
some such and it was very active for a while but I guess eventually went
dark. Maybe he'd be interested in passing the code off to you and dumping the
existing data if he still has it and thinks it is still relevant. Then it
could be put up at railsbeginner.com or railsdocumentation.com or what have
you.

I was looking for help for well over a year, and eventually gave up
after getting no real responses and then losing the domain :confused: The
data is still intact, but it's barely more than a beast forum anymore.
At that point, I'm not sure what the value is over something like
railsforum then. It used to have an arbitrary point and ribbon system
to sort of reward folks for helping others out though.

We're talking about moving the Mephisto wiki (which is riddled with
spam) to a custom mephisto setup and appointing writers to maintain
the docs. This is how prototypejs.org is setup
(http://prototypejs.org/api, also with Mephisto). Ultimately though,
it doesn't matter what system you use, just that there's an active
team keeping things current.

Has anyone looked at what other OSS projects have done differently to
enable successful doc projects created or contributed to by the
community? I'm thinking in particular of the django book, and maybe
also php.net. What do they do differently to address the people
problems that we see in the Rails community?

- Rob
http://robsanheim.com

+1 on the OSS book idea. I have always felt that rails api docs are
not as bad as people make it sound like. I like django style book
idea.

I guess irc/mailing list are good enough for question/answer. There is
no point in spoon feeding.

I brought it up in a previous post, but making docs available for
older rails milestones would be useful. PHP docs, for example, show
what version of PHP a method was added in or is supported for.

Not everyone uses the latest version of rails now. Back in the old
days you'd be expected to update and use the latest rails version, but
rails has entered it's support days now. :slight_smile:

We're not writing a manual for a microwave that doesn't change after someone decides on the specs and thinks about the user interface, this is documentation for a constantly evolving framework. I think we should keep the documentation close to the source and preferably in the source where you're constantly reminded that any patch should also mean an update to the surrounding documentation.

For external documentation you need either intimate knowledge of way the source works, or use the current API docs as a source. That sounds like a maintenance hell to me.

Higher level documentation could be sustainable because it would only describe concepts, and not implementation details (.ie an explanation what ActiveRecord is and what problems it solves.) Higher level documentation is mostly useful for newcomers and they like to dive in headfirst, not spend a whole day reading about architecture.

Long story short: good API docs, good examples, screencasts, blog posts and a forum/mailinglist seem like the way to go and I think we're already pretty well supplied in those areas.

Manfred

But it may not get right feel of the framework for a newcomer, and as long as Rails is opinionated software, Djangish kind of a book may be a good idea to fill in this gap.

I disagree that a forum and/or mailing list rocks - it's good enough,
but it's not awesome. Having a system where questions are tagged and
moderated is very different.

Also, keep in mind what kind of questions people might have. In IRC,
some guy wondered why restful_authentication didn't work. He had
installed the plugin, and login/logout worked, but "a users could
still see the posts other users have made". When I told him that he
needed to change the finders in the controller to find the posts from
the current user (current_user.posts), he said "that didn't work" -
because he hadn't set up a Post.belongs_to :user and
User.has_many :posts. He had no idea on how to achieve this.

You could say that this was pretty retarded, and I would agree. He
simply didn't understand anything about how rails works, and when I
told him that he needed to set up the associations, he came back to me
and asked why he got all these error messages - he hadn't added a
user_id column to the posts table, and didn't understand why he had to
do that. Still, after some moderations and tagging, and with an added
write-up on how to do what he wanted to do - authenticate users and
then scope finders by the current user - would be a good resource for
rails beginners. You could argue that it's not up to the core team to
document usage of plugins, but then again why not? Most Rails books
include some plugin usage, and pretty much all rails apps are using
plugins anyway.

I could just get at it, and make this railsbeginners.com, but that's
pointless because of the reasons mentioned above - we don't need
another one-man doc site, we need a doc team, listed on
rubyonrails.com/core.

I also like the book idea and I tend to agree with the latter.

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.

I've been mulling over a distributed mechanism to supply that need the other day. Like: mark up content (tutorials, walkthroughs, q&a) with some kind of suited Microformat "in the wild", have a pub/sub mechanism in place and display the resources at central places, which also might be moderated/gardened by volunteers. Apps like railsweenie could add the necessary Microformats (or whatever conventions) automatically.

Maybe this might be a more powerful approach than creating yet another walled community site?

You go to google, type in "ruby on rails", click on "documentation" and voila:

http://www.rubyonrails.org/docs

I think this lists a good number of resources to get you started.

Manfred

There is no single (and free) resource one can use. And I don't think
rubyonrails.org/docs is good enough. We don't need articles or
(costly) books, we need one website (yes, one. one one one. 1) where
you can figure out what you need to figure out to get started. Which
should be supported and maintained by a core documentation team, that
also makes sure the information on that webpage is kept up to date. At
least tagged as "outdated" if it's not.

With that said, I really like Sven Fuchs' idea. He has a good point -
there's a lot of information out there, it's just hard to find it. And
hard to know if it's outdated. Having a system which simply is a bunch
of tagged and categorized links sounds like a very good idea - that
means the dev core team doesn't have to actually write stuff, just
categorize it.

What's wrong with just directing new people to "Agile Web Development
with Rails"?

So long as you keep the API documentation up to date, I think
professional, fulltime writers and educators can write better
introductory documentation than any of us.

Also, the very first page of the API documentation starts out with a perfectly fine introduction that should get any halfway decent developer started:

http://api.rubyonrails.com/

Kind regards,
Thijs

Long story short, it is a bit outdated after 2.0 release. We don't want 2.0 features being discovered by masses by the time of 3.0 release, right?

It doesn't matter how much we argue back and forth on this. Newbies
has a problem getting started with rails without having to pay for a
book. That is a fact. It doesn't matter if the API introduction page
"should" get them going, or that they "should" find what they need by
googling - they are, as of now, usually not able to get started easily
(without paying for it), and that's the problem that needs to be fixed
by a core doc team.

Well, what's holding you back? Start writing! :slight_smile:

Kind regards,
Thijs