I emailed this list a while back about Ruby on Rails Tutorial, a project to make a high-quality and up-to-date introductory tutorial book for Rails---basically, a good answer to the question, "Where should I start if I want to learn Rails?"
In preparation for the main project, I've recently spent some time developing a system to make nice PDF and HTML books at the same time (see, e.g., the sample document at http://www.railstutorial.org/sample), and now it's time to start writing the actual book. I want to design the tutorial so that (a) newbies find it interesting and comprehensible and (b) Rails experts are enthusiastic about recommending it. Since subscribers to this list are likely to be Rails experts, you are in a position to help me achieve goal (b). In particular, I have two key questions about the book's content:
1. Which testing framework should I use? Given my knowledge (experience with Test::Unit and RSpec, among others) and my audience (beginners), the choice boils down to:
(a) Test::Unit
Pros: comes bundled with Rails, is "good enough" Cons: needs either fixtures (fragile) or something like Mocha (external dependency); many, perhaps most, advanced Rails developers eventually move on to something else
(b) RSpec
Pros: nicely designed, I know it well (it's my current primary test framework) Cons: less standard than Test::Unit, adds an external dependency
2. The tutorial will teach Rails by developing a substantial sample application, and the leading candidate for the sample app is status updates with asymmetric following---i.e., a tiny Twitter clone.
Pros: A nice size (not too big, not too small*) with an interesting data model; Twitter is hot right now, and it's written in Rails to boot Cons: Might seem too trendy, could be dated in a year or two
*Don't worry that it might be too small; making it bigger is easy. Add support for @reply threads, direct messaging, RSS feeds, and search---bam! that's 2-3 extra chapters right there.
So, what do you think? Test::Unit or RSpec? A tiny Twitter sample app, or something else? Which choices would make for a tutorial you personally would recommend? Feel free to email general suggestions; for quick feedback, I've set up a survey form here:
Re: a project...
Twitter brings with it an external dependency (twitter itself) which may be
down, slow, or otherwise unavailable (imagine someone wanting to learn with
your tutorial while travelling without net access for parts of the trip).
A contact manager system might be a decent 'generic' project which hasn't
been done too much before. Blogs and twitter clients have been done to
death (not specifically in Rails, just as web tutorial projects). A contact
manager can incorporate and demonstrate authentication levels, logging,
testing, UI sexiness, and more, while remaining relatively self-contained.
It can be as complex or as basic as you need it to be.
Good luck with the project :)
On Fri, Sep 18, 2009 at 4:35 PM, Michael Hartl <mich...@michaelhartl.com>wrote:
> I emailed this list a while back about Ruby on Rails Tutorial, a
> project to make a high-quality and up-to-date introductory tutorial
> book for Rails---basically, a good answer to the question, "Where
> should I start if I want to learn Rails?"
> In preparation for the main project, I've recently spent some time
> developing a system to make nice PDF and HTML books at the same time
> (see, e.g., the sample document at
> http://www.railstutorial.org/sample), and now it's time to start
> writing the actual book. I want to design the tutorial so that (a)
> newbies find it interesting and comprehensible and (b) Rails experts
> are enthusiastic about recommending it. Since subscribers to this list
> are likely to be Rails experts, you are in a position to help me
> achieve goal (b). In particular, I have two key questions about the
> book's content:
> 1. Which testing framework should I use? Given my knowledge
> (experience with Test::Unit and RSpec, among others) and my audience
> (beginners), the choice boils down to:
> (a) Test::Unit
> Pros: comes bundled with Rails, is "good enough"
> Cons: needs either fixtures (fragile) or something like Mocha
> (external dependency); many, perhaps most, advanced Rails developers
> eventually move on to something else
> (b) RSpec
> Pros: nicely designed, I know it well (it's my current primary test
> framework)
> Cons: less standard than Test::Unit, adds an external dependency
> 2. The tutorial will teach Rails by developing a substantial sample
> application, and the leading candidate for the sample app is status
> updates with asymmetric following---i.e., a tiny Twitter clone.
> Pros: A nice size (not too big, not too small*) with an interesting
> data model; Twitter is hot right now, and it's written in Rails to
> boot
> Cons: Might seem too trendy, could be dated in a year or two
> *Don't worry that it might be too small; making it bigger is easy. Add
> support for @reply threads, direct messaging, RSS feeds, and
> search---bam! that's 2-3 extra chapters right there.
> So, what do you think? Test::Unit or RSpec? A tiny Twitter sample app,
> or something else? Which choices would make for a tutorial you
> personally would recommend? Feel free to email general suggestions;
> for quick feedback, I've set up a survey form here:
> Twitter brings with it an external dependency (twitter itself) which may be > down, slow, or otherwise unavailable (imagine someone wanting to learn with > your tutorial while travelling without net access for parts of the trip).
Thanks for the feedback. Perhaps I wasn't clear: the idea is to *write* a small, stripped-down version of Twitter as a way to teach Rails, not to make a Twitter client or integrate with the real Twitter in any way. Such an application might not be particularly useful---it's hard to imagine why you'd want to launch your own version of Twitter---but it would be instructive. And that is, after all, the main point of a tutorial.
Ahhh - yeah, I jumped to 'twitter client'. I'd still maintain a 'contact
manager'-type app might be a bit more accessible to more people, but a
twitter server wouldn't be bad.
On Fri, Sep 18, 2009 at 6:25 PM, Michael Hartl <mich...@michaelhartl.com>wrote:
> > Twitter brings with it an external dependency (twitter itself) which may
> be
> > down, slow, or otherwise unavailable (imagine someone wanting to learn
> with
> > your tutorial while travelling without net access for parts of the trip).
> Thanks for the feedback. Perhaps I wasn't clear: the idea is to
> *write* a small, stripped-down version of Twitter as a way to teach
> Rails, not to make a Twitter client or integrate with the real Twitter
> in any way. Such an application might not be particularly
> useful---it's hard to imagine why you'd want to launch your own
> version of Twitter---but it would be instructive. And that is, after
> all, the main point of a tutorial.
Thinking back to when I was learning Rails, I really didn't have any
sort of Ruby grounding at all.
As a result, I knew how to use Models and Controllers etc. long before
I fully realised that these were just examples of Ruby classes.
For the same reason that you should learn French before trying to
write French poetry, your readers should learn Ruby before they learn
to write in Rails. I'd love to see an intro to Rails book that did
this!
In my opinion, a Twitter copy would be fine. Best to use a format that
your users are really comfortable with. That way the focus is on
learning how Ruby and Rails work and not on learning how a particular
website works.
As far as testing goes... interesting dilemma.
On one side, by introducing Rspec, you could introduce your readers to
gems. Let them know that Ruby offers a vast collection of libraries
that you can pick and choose depending on your needs. I find rspec
better for BDD too. The "should create a new user" and "should not add
a comment" are easier to understand and follow than "test creating
users" or "test adding comments" so perhaps your readers will find
that a more palatable introduction to testing?
On the other side, you're introducing newbs to Rails. So perhaps going
along with the defaults may be less intimidating. To address the issue
of fixtures, you could use FactoryGirl instead. That way you're still
sticking to Test::Unit, you can introduce the concept of gems and your
avoiding fixtures.
If your goal is to teach someone to work with Rails then you want to
equip them with the best tools for the job. In my opinion that's
Rspec.
I'd be interested in seeing the progress of your book.
> > Twitter brings with it an external dependency (twitter itself) which may be
> > down, slow, or otherwise unavailable (imagine someone wanting to learn with
> > your tutorial while travelling without net access for parts of the trip).
> Thanks for the feedback. Perhaps I wasn't clear: the idea is to
> *write* a small, stripped-down version of Twitter as a way to teach
> Rails, not to make a Twitter client or integrate with the real Twitter
> in any way. Such an application might not be particularly
> useful---it's hard to imagine why you'd want to launch your own
> version of Twitter---but it would be instructive. And that is, after
> all, the main point of a tutorial.
I have to agree Gavin. Most rails books start with the Rails magic,
but you never really get it enough to be good at Rails until you start
learning Ruby. Then it really starts to click and your skills begin to
increase more rapidly. I would recommend teaching Ruby along the way
with rails. Not delaying rails until after ruby, nor ruby after rails,
but teaching rails and embedding ruby structures, backgrounds, and
core language along the way.
Brian Burridge
peepnote.com, wombeat.com, mileyworld.com
On Sep 18, 2009, at 7:00 PM, Gavin <ga...@thinkersplayground.com> wrote:
> Thinking back to when I was learning Rails, I really didn't have any
> sort of Ruby grounding at all.
> As a result, I knew how to use Models and Controllers etc. long before
> I fully realised that these were just examples of Ruby classes.
> For the same reason that you should learn French before trying to
> write French poetry, your readers should learn Ruby before they learn
> to write in Rails. I'd love to see an intro to Rails book that did
> this!
> In my opinion, a Twitter copy would be fine. Best to use a format that
> your users are really comfortable with. That way the focus is on
> learning how Ruby and Rails work and not on learning how a particular
> website works.
> As far as testing goes... interesting dilemma.
> On one side, by introducing Rspec, you could introduce your readers to
> gems. Let them know that Ruby offers a vast collection of libraries
> that you can pick and choose depending on your needs. I find rspec
> better for BDD too. The "should create a new user" and "should not add
> a comment" are easier to understand and follow than "test creating
> users" or "test adding comments" so perhaps your readers will find
> that a more palatable introduction to testing?
> On the other side, you're introducing newbs to Rails. So perhaps going
> along with the defaults may be less intimidating. To address the issue
> of fixtures, you could use FactoryGirl instead. That way you're still
> sticking to Test::Unit, you can introduce the concept of gems and your
> avoiding fixtures.
> If your goal is to teach someone to work with Rails then you want to
> equip them with the best tools for the job. In my opinion that's
> Rspec.
> I'd be interested in seeing the progress of your book.
> On Sep 18, 11:25 pm, Michael Hartl <mich...@michaelhartl.com> wrote:
>>> Twitter brings with it an external dependency (twitter itself)
>>> which may be
>>> down, slow, or otherwise unavailable (imagine someone wanting to
>>> learn with
>>> your tutorial while travelling without net access for parts of the
>>> trip).
>> Thanks for the feedback. Perhaps I wasn't clear: the idea is to
>> *write* a small, stripped-down version of Twitter as a way to teach
>> Rails, not to make a Twitter client or integrate with the real
>> Twitter
>> in any way. Such an application might not be particularly
>> useful---it's hard to imagine why you'd want to launch your own
>> version of Twitter---but it would be instructive. And that is, after
>> all, the main point of a tutorial.
This is great feedback. The plan has always been to avoid a big
up-front section on Ruby---people reading a Rails tutorial usually
want to learn Rails, not Ruby per se, and having a 50-75 page Ruby
intro is a big pill to swallow. One of my mantras when writing
"RailsSpace" was "don't stray too far from the browser"; in other
words, we're making web apps here, not writing general Ruby programs.
On the other hand, you've convinced me that really cranking up the
dial on the Ruby content is a good idea, both as a way to demystify
some of the Rails magic and to empower the reader by conveying a
deeper understanding of the underlying language.
On Fri, Sep 18, 2009 at 4:26 PM, Brian <bburr...@gmail.com> wrote:
> I have to agree Gavin. Most rails books start with the Rails magic,
> but you never really get it enough to be good at Rails until you start
> learning Ruby. Then it really starts to click and your skills begin to
> increase more rapidly. I would recommend teaching Ruby along the way
> with rails. Not delaying rails until after ruby, nor ruby after rails,
> but teaching rails and embedding ruby structures, backgrounds, and
> core language along the way.
> Brian Burridge
> peepnote.com, wombeat.com, mileyworld.com
> On Sep 18, 2009, at 7:00 PM, Gavin <ga...@thinkersplayground.com> wrote:
>> Michael,
>> Thinking back to when I was learning Rails, I really didn't have any
>> sort of Ruby grounding at all.
>> As a result, I knew how to use Models and Controllers etc. long before
>> I fully realised that these were just examples of Ruby classes.
>> For the same reason that you should learn French before trying to
>> write French poetry, your readers should learn Ruby before they learn
>> to write in Rails. I'd love to see an intro to Rails book that did
>> this!
>> In my opinion, a Twitter copy would be fine. Best to use a format that
>> your users are really comfortable with. That way the focus is on
>> learning how Ruby and Rails work and not on learning how a particular
>> website works.
>> As far as testing goes... interesting dilemma.
>> On one side, by introducing Rspec, you could introduce your readers to
>> gems. Let them know that Ruby offers a vast collection of libraries
>> that you can pick and choose depending on your needs. I find rspec
>> better for BDD too. The "should create a new user" and "should not add
>> a comment" are easier to understand and follow than "test creating
>> users" or "test adding comments" so perhaps your readers will find
>> that a more palatable introduction to testing?
>> On the other side, you're introducing newbs to Rails. So perhaps going
>> along with the defaults may be less intimidating. To address the issue
>> of fixtures, you could use FactoryGirl instead. That way you're still
>> sticking to Test::Unit, you can introduce the concept of gems and your
>> avoiding fixtures.
>> If your goal is to teach someone to work with Rails then you want to
>> equip them with the best tools for the job. In my opinion that's
>> Rspec.
>> I'd be interested in seeing the progress of your book.
>> On Sep 18, 11:25 pm, Michael Hartl <mich...@michaelhartl.com> wrote:
>>>> Twitter brings with it an external dependency (twitter itself)
>>>> which may be
>>>> down, slow, or otherwise unavailable (imagine someone wanting to
>>>> learn with
>>>> your tutorial while travelling without net access for parts of the
>>>> trip).
>>> Thanks for the feedback. Perhaps I wasn't clear: the idea is to
>>> *write* a small, stripped-down version of Twitter as a way to teach
>>> Rails, not to make a Twitter client or integrate with the real
>>> Twitter
>>> in any way. Such an application might not be particularly
>>> useful---it's hard to imagine why you'd want to launch your own
>>> version of Twitter---but it would be instructive. And that is, after
>>> all, the main point of a tutorial.
> This is great feedback. The plan has always been to avoid a big
> up-front section on Ruby---people reading a Rails tutorial usually
> want to learn Rails, not Ruby per se, and having a 50-75 page Ruby
> intro is a big pill to swallow. One of my mantras when writing
> "RailsSpace" was "don't stray too far from the browser"; in other
> words, we're making web apps here, not writing general Ruby programs.
> On the other hand, you've convinced me that really cranking up the
> dial on the Ruby content is a good idea, both as a way to demystify
> some of the Rails magic and to empower the reader by conveying a
> deeper understanding of the underlying language.
> Thanks!
> Michael
> On Fri, Sep 18, 2009 at 4:26 PM, Brian <bburr...@gmail.com> wrote:
>> I have to agree Gavin. Most rails books start with the Rails magic,
>> but you never really get it enough to be good at Rails until you
>> start
>> learning Ruby. Then it really starts to click and your skills
>> begin to
>> increase more rapidly. I would recommend teaching Ruby along the way
>> with rails. Not delaying rails until after ruby, nor ruby after
>> rails,
>> but teaching rails and embedding ruby structures, backgrounds, and
>> core language along the way.
>> Brian Burridge
>> peepnote.com, wombeat.com, mileyworld.com
>> On Sep 18, 2009, at 7:00 PM, Gavin <ga...@thinkersplayground.com>
>> wrote:
>>> Michael,
>>> Thinking back to when I was learning Rails, I really didn't have any
>>> sort of Ruby grounding at all.
>>> As a result, I knew how to use Models and Controllers etc. long
>>> before
>>> I fully realised that these were just examples of Ruby classes.
>>> For the same reason that you should learn French before trying to
>>> write French poetry, your readers should learn Ruby before they
>>> learn
>>> to write in Rails. I'd love to see an intro to Rails book that did
>>> this!
>>> In my opinion, a Twitter copy would be fine. Best to use a format
>>> that
>>> your users are really comfortable with. That way the focus is on
>>> learning how Ruby and Rails work and not on learning how a
>>> particular
>>> website works.
>>> As far as testing goes... interesting dilemma.
>>> On one side, by introducing Rspec, you could introduce your
>>> readers to
>>> gems. Let them know that Ruby offers a vast collection of libraries
>>> that you can pick and choose depending on your needs. I find rspec
>>> better for BDD too. The "should create a new user" and "should
>>> not add
>>> a comment" are easier to understand and follow than "test creating
>>> users" or "test adding comments" so perhaps your readers will find
>>> that a more palatable introduction to testing?
>>> On the other side, you're introducing newbs to Rails. So perhaps
>>> going
>>> along with the defaults may be less intimidating. To address the
>>> issue
>>> of fixtures, you could use FactoryGirl instead. That way you're
>>> still
>>> sticking to Test::Unit, you can introduce the concept of gems and
>>> your
>>> avoiding fixtures.
>>> If your goal is to teach someone to work with Rails then you want to
>>> equip them with the best tools for the job. In my opinion that's
>>> Rspec.
>>> I'd be interested in seeing the progress of your book.
>>> On Sep 18, 11:25 pm, Michael Hartl <mich...@michaelhartl.com> wrote:
>>>>> Twitter brings with it an external dependency (twitter itself)
>>>>> which may be
>>>>> down, slow, or otherwise unavailable (imagine someone wanting to
>>>>> learn with
>>>>> your tutorial while travelling without net access for parts of the
>>>>> trip).
>>>> Thanks for the feedback. Perhaps I wasn't clear: the idea is to
>>>> *write* a small, stripped-down version of Twitter as a way to teach
>>>> Rails, not to make a Twitter client or integrate with the real
>>>> Twitter
>>>> in any way. Such an application might not be particularly
>>>> useful---it's hard to imagine why you'd want to launch your own
>>>> version of Twitter---but it would be instructive. And that is,
>>>> after
>>>> all, the main point of a tutorial.
