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 (Prototype API Documentation | Home (Deprecated URL), 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

+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