Rails core team - only development?

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.

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

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.

My two cents, anyway.

Regards, Tomas Jogin

They can do so now by creating documentation patches. The API documentation is currently the only 'official' Rails documentation in existence.

Kind regards, Thijs

The fact that an API is considered official documentation is a bit alarming, aint it?

Why exactly?

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.

As for starting a book, there's the start to an open source book on Rails here: http://www.railsdocumentation.org/book.html

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. :slight_smile: I've got a Basecamp, Lighthouse, blah blah blah to coordinate all the efforts.

--Jeremy

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.

--Jeremy

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.

As for starting a book, there's the start to an open source book on Rails here:Create A Perfect Resume In 5 Minutes! | Online Resume Builder

It's out of date and not a lot of content at this point

[snip]

Exactly my point. :slight_smile: 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.

My two cents, anyway.

Jeff softiesonrails.com

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).

Jeremy McAnally wrote:

> 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:

Ruby on Rails — A web-app framework that includes everything needed to create database-backed web applications according to the Model-View-Controller (MVC) pattern.

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.

Scott

For the record, the manuals are being worked on. :slight_smile:

They are in a sad state, to be sure.

--Jeremy

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 believe that the ruse project is in use on RubyGarden now (not positive). It's written in Ruby and offers a lot of the features you mention.

It seems that all of the web pages related to it or using it are down at the moment, but maybe they'll get them back up soon. :slight_smile:

--Jeremy

See, that's what I'm saying... :slight_smile:

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?

August Lilleaas wrote:

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 :wink: ) 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.

Michael Slater wrote:

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.