Hey folks,
Something that I've often encountered (as a new developer) is tutorials without the finished project available - so, what I did with my time today was follow the getting started guide (both for rails 3 and rails 3.1) and put them up on Github[1] - is that something that the guide should have a link to, or what? Has something like this been discussed and shot down before?
Cheers, James Gifford
[1] https://github.com/jrgifford/Ruby-on-Rails-Getting-Started
This is an interesting proposal. We could certainly explore it.
Assuming people are interested in actual files with the application[*] in my view the natural way to store such example application would be the very railties/guides directory. That would be coherent and would fit within the workflow of maintenance of the getting started guide. Much better for maintenance than a link to some repo somewhere.
If we checked in such example code, it should be editable from docrails in my view. We'd add an exception to the only-docs rule.
Let me think a bit more about it, may contact you off-list if we go on with it.
Thanks!
-- fxn
[*] I say "assuming", because I have never downloaded "source code of the book" kind of apps or tarballs, but guess people do it, don't really know.
I think it would be extremely helpful for people to see the example application for the Getting Started guide. Great idea, James!
I’d be interested in assisting with this moving forward if I’m able. Feel free to include me off list. I think if I’d had today’s guide site - and demonstration app available next to it - when I discovered Rails 5 years ago I’d have been amazed. This is a great idea!
Particularly, I slept in almost all of my classes from my first classes in life to college classes.
When teachers are introducing a subject, they spend a lot of time introducing it and I get to sleep. When I wake up I've lost several of the significant bits and then I come back to sleep because I won't understand the class anyway...
So I have almost always learned by books...
The exception is the situation where the classes are subverted. You start the class with a challenge. A real-life challenge. Then, it will get my attention and I'll try my best to understand what the teacher is talking about that will eventually led me to solve that kind of problem. When they start talking about a subject from the introduction, I never know exactly what is that useful for...
I know there are others like me. For those, presenting the final solution first, could help them learning and following the guide.
You can say "you can do an application like [this] with Rails by following this guide. The application will allow you to...". Then, the reader is invited to take a look at the final built application first.
Then, the guide will explain step by step how to get there.
I know that there are other sort of guys that will prefer the traditional model, but maybe this is something that could be tried...
The problem here is that it is a bit complicated to write good guides for everyone. When I started learning Rails, for instance, I already knew a lot about general programming, web programming, databases, etc. I just wanted to know how to get things done with Rails. Someone that is starting his programming life with Rails will need a completely different kind of documentation.
Trying to get a "universal" guide for every public is a challenge at best.
On the other hand, trying to organize the guides in sections (begginer, intermediate and advanced) is not feasible in my opinion since it would require much more effort.
So, I have to tell you, specially you, Xavier, congratulations for all the hard work that have been done with the Rails documentation effort. It is a definitely hard task that has being done in the best possible way!
I take my hats off to you and the documentation team!
Cheers,
Rodrigo.
I think the single biggest advantage to the current guides is how much like "API documentation with training wheels" they are. People can dip and out of a relevant section, learn a lot of useful information quickly - and get back to coding.
Having the same application run through the entire guide, as a point of illustration is great - and having this application available in some way and maintained is great. Any wholesale change to move the Guides in a more narrative direction doesn't sound like a wise idea to me. That's what books are for. The guides are done well right now.
Cheers, D
Yeah, I agree with you. I hope I didn't suggest "moving the guides in a more narrative direction" 
If that was your impression, then maybe it's my fault since I'm probably not that good with English yet 
I really don't know what are the current guide lines for writing the Rails guides as they were written, but I can say it is working. Somehow it seems that every one is pleased by the current guide format and topics (me included)
Cheers!
So the general consensus is that it'd be a good idea, but the problem is implementing and maintaining it?
Cheers, James Gifford http://jamesrgifford.com
If you could write the Getting Started guide with some automated method of generating the example application as you go and perhaps having it validate that the output is exactly what we claim it to be, I think this would be a good way to keep it “maintainable”.
I’m currently doing this myself for the Sprockets internals guide (https://github.com/radar/guides/blob/master/sprockets/sprockets.markdown) that I am writing using another project I wrote called Muse (http://github.com/radar/muse). It validates that code examples contained within the .muse file are accurate as per the repositories and does this using RSpec tests. You could probably do it with Test::Unit too.
You can get the gist of how it works by looking at the feature for a valid markdown file that shows off testing and generation of these documents: https://github.com/radar/muse/blob/master/features/valid_markdown.feature
I think it could be easily adapted to support the Rails guide format.
Ryan something like this would be awesome. Adding some kind of test coverage to the guides is something that has been in the wish list for a long time. Possibly some kind of system testing.
Regarding the application, yes let's do it. We can put it under the (new) folder
railties/guides/code/getting_started
James, would you like to prepare a pull request for that? Ideally the application should have the same code verbatim, exact, whitespace and all.
If you do, please ping me and I'll apply.
Xavier, I'll prepare that sometime in the next week and submit the pull request.
Cheers, James Gifford http://jamesrgifford.com
Boom:
https://github.com/lifo/docrails/pull/65
As per the comment on the pull request, if someone could tell me how to add an explanation and link to the guide, I'll toss that in as well.
Boom:
https://github.com/lifo/docrails/pull/65
As per the comment on the pull request, if someone could tell me how to add an explanation and link to the guide, I'll toss that in as well.
Awesome! Could you please prepare de pull request for rails/rails instead?
Keep up to date with Rails on Twitter and This Week in Rails
Policies: Conduct, License, Maintenance, Security, Trademarks