Rails - Jul 2005 - Newbie: Anything like [ www.php.net/manual/ ] for Ruby & RoR ?

Hi,

I''m a new almost convert to the RoR side, but I''m struggling
to find
easily digested information along the lines of PHP.net manual. Is  
there something like it that I haven''t found ?

I bought both the PickAxe II and the RoR book (and is trying to read  
through them, but not really a RTFM kind-of-guy) and keep on  
forgetting where I read that bit of info on how to do something.

The api.rubyonrails.com  is extensive, but really truly badly  
implemented. There not even a search (?)

I am not a CS guy, but I managed to pick up PHP because it was easy  
to learn and had good easy to digest information, and I''m hoping for  
the same here with RoR & Ruby.

Kind regards,

Mats

----
"TextMate, coding with an incredible sense of joy and ease"
- www.macromates.com -

I feel the same way; the API docs could use some fleshing out, even if
it''s not feasible to get them to the same level as the PHP docs.

Maybe this is something the community can get together and work on.
There should definitely be some good, digestible reference info on
Rails, to hit that middle ground between the API and hand-holders
(like the howtos and other stuff on the site).


========= ========= ========= ========= ========David Demaree -
ddemaree-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org - http://velocipedist.com/


On 7/14/05, Mats Persson <mats-uGq4Pdis5ybkYMGBc/C6ZA@public.gmane.org>
wrote:
> 
> Hi,
> 
> I''m a new almost convert to the RoR side, but I''m
struggling to find
> easily digested information along the lines of PHP.net manual. Is
> there something like it that I haven''t found ?
> 
> I bought both the PickAxe II and the RoR book (and is trying to read
> through them, but not really a RTFM kind-of-guy) and keep on
> forgetting where I read that bit of info on how to do something.
> 
> The api.rubyonrails.com  is extensive, but really truly badly
> implemented. There not even a search (?)
> 
> I am not a CS guy, but I managed to pick up PHP because it was easy
> to learn and had good easy to digest information, and I''m hoping
for
> the same here with RoR & Ruby.
> 
> Kind regards,
> 
> Mats
> 
> ----
> "TextMate, coding with an incredible sense of joy and ease"
> - www.macromates.com -
> 
> 
> _______________________________________________
> Rails mailing list
> Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
> http://lists.rubyonrails.org/mailman/listinfo/rails
> 

-- 

=== === === === === === === === === === ===
==ddemaree-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org  
http://practicalmadness.com/

On 7/14/05, Mats Persson <mats-uGq4Pdis5ybkYMGBc/C6ZA@public.gmane.org>
wrote:
> I''m a new almost convert to the RoR side, but I''m
struggling to find
> easily digested information along the lines of PHP.net manual. Is
> there something like it that I haven''t found ?
> 
> I bought both the PickAxe II and the RoR book (and is trying to read
> through them, but not really a RTFM kind-of-guy) and keep on
> forgetting where I read that bit of info on how to do something.
> 
> The api.rubyonrails.com  is extensive, but really truly badly
> implemented. There not even a search (?)
> 
> I am not a CS guy, but I managed to pick up PHP because it was easy
> to learn and had good easy to digest information, and I''m hoping
for
> the same here with RoR & Ruby.
Try RailDock... it''s still young, but I believe the goal of the
project is to provide searchable, annotatable documentation for RoR.

http://raildock.mytechsupport.com/

Cheers,

bs.

On 7/14/05, Ben Schumacher
<benschumacher-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
wrote:
> Try RailDock... it''s still young, but I believe the goal of the
> project is to provide searchable, annotatable documentation for RoR.
> 
> http://raildock.mytechsupport.com/
I should caveat that this current supports Rails API reference only,
not the Ruby language as a whole.

bs.

If you''re brand new, you may have missed the thread a few days ago, but
a coworker of mine, Duane Johnson, put together a little rails 
documentation project over this last weekend, that is currently hosted 
on our company''s dev server, but is publicly available (i think he 
plan''s on releasing the source code when it''s a little further
along).

http://raildock.mytechsupport.com/

It''s got some pretty cool search functionality, and allows registered 
users to add snippets, etc.  to the documentation.  You may not find 
much of these custom comments since it''s only been around for 4-5 days 
now, but this may be something like what you''re looking for. 
It''s
certainly prettier that the http://www.php.net/manual ;-) 
<http://www.php.net/manual>

Ben Robison

David Demaree wrote:
>I feel the same way; the API docs could use some fleshing out, even if
>it''s not feasible to get them to the same level as the PHP docs.
>
>Maybe this is something the community can get together and work on.
>There should definitely be some good, digestible reference info on
>Rails, to hit that middle ground between the API and hand-holders
>(like the howtos and other stuff on the site).
>
>
>========= ========= ========= ========= ========>David Demaree -
ddemaree-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org - http://velocipedist.com/
>
>
>On 7/14/05, Mats Persson
<mats-uGq4Pdis5ybkYMGBc/C6ZA@public.gmane.org> wrote:
>  
>
>>Hi,
>>
>>I''m a new almost convert to the RoR side, but I''m
struggling to find
>>easily digested information along the lines of PHP.net manual. Is
>>there something like it that I haven''t found ?
>>
>>I bought both the PickAxe II and the RoR book (and is trying to read
>>through them, but not really a RTFM kind-of-guy) and keep on
>>forgetting where I read that bit of info on how to do something.
>>
>>The api.rubyonrails.com  is extensive, but really truly badly
>>implemented. There not even a search (?)
>>
>>I am not a CS guy, but I managed to pick up PHP because it was easy
>>to learn and had good easy to digest information, and I''m
hoping for
>>the same here with RoR & Ruby.
>>
>>Kind regards,
>>
>>Mats
>>
>>----
>>"TextMate, coding with an incredible sense of joy and ease"
>>- www.macromates.com -
>>
>>
>>_______________________________________________
>>Rails mailing list
>>Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
>>http://lists.rubyonrails.org/mailman/listinfo/rails
>>
>>    
>>
>
>
>  
>


No virus found in this outgoing message.
Checked by AVG Anti-Virus.
Version: 7.0.323 / Virus Database: 267.8.15/49 - Release Date: 7/14/2005

_______________________________________________
Rails mailing list
Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
http://lists.rubyonrails.org/mailman/listinfo/rails

On 14-Jul-05, at 4:41 PM, Ben Schumacher wrote:
> I should caveat that this current supports Rails API reference only,
> not the Ruby language as a whole.
Duane, any plans of integrating the Ruby docs into RailDock? It would  
be cool to lookup the built-in Ruby classes/modules and the Rails API  
in one shot.

Thanks for RailDock, BTW -- it''s a great resource.

/Jeff

On Jul 14, 2005, at 4:16 PM, Jeffrey Hardy wrote:
> On 14-Jul-05, at 4:41 PM, Ben Schumacher wrote:
>> I should caveat that this current supports Rails API reference only,
>> not the Ruby language as a whole.
> Duane, any plans of integrating the Ruby docs into RailDock? It  
> would be cool to lookup the built-in Ruby classes/modules and the  
> Rails API in one shot.
>
> Thanks for RailDock, BTW -- it''s a great resource.
Yes, it should be a simple task to integrate the Ruby docs.  I''ll  
look in to that this evening.

Thanks for everyone''s thoughts and work on this.  The next release is  
going to be the public one, and it''s looking pretty sweet.

Duane Johnson
(canadaduane)

On 14 Jul 2005, at 21:45, Ben Robison wrote:
> http://raildock.mytechsupport.com/  It''s got some pretty cool  
> search functionality, and allows registered users to add snippets,  
> etc.  to the documentation.  You may not find much of these custom  
> comments since it''s only been around for 4-5 days now, but this
may
> be something like what you''re looking for.  It''s
certainly prettier
> that the http://www.php.net/manual ;-)
Had a look at RailDock, but although it might be good down the road  
it sure does not help me today. ( only 2 items right now ?! )

As for prettier than PHP.net''s manual. Well, pardon me for saying  
this, but that''s about as important to me - or any other real users -  
as getting paid for my work in new crisp clean notes (rather than  
wrinkly used ones).  I don''t care, I just want to get paid the full  
amount.

PHP.net''s manual has many flaws, but if you haven''t used it  
extensively then you''ve missed one of the best features on the web.  
90% of the time it''s clear, concise and precise and answers your  
question. That''s the way any manual should be ! (if you are  
ideologically opposed to PHP, then wake up and ask some questions  
from it and get the answers immediately and conveniently)


On 15 Jul 2005, at 00:43, Duane Johnson wrote:
>> Duane, any plans of integrating the Ruby docs into RailDock? It  
>> would be cool to lookup the built-in Ruby classes/modules and the  
>> Rails API in one shot.
> Yes, it should be a simple task to integrate the Ruby docs.  I''ll
> look in to that this evening.
> Thanks for everyone''s thoughts and work on this.  The next release
> is going to be the public one, and it''s looking pretty sweet.
Duane, while you''re still developing the stuff please take these  
comments onboard:

-- although looks good certainly is nice, it''s NOT the most important  
factor. Actually it''s pretty far down the list. Usability and ease of  
use (which is really clarity of structure and design) scores 100  
times higher.

--  the php manual supports this:  www.php.net/<NAME_OF_FUNCTION>    
which redir''s to the relevant manual page, or in the case of a non- 
exact match shows you a list of possibles.  (there are several entry  
points for this, so it''s not only in the root of site)
This is a brilliant implementation, and you should really do the same !!

-- the php manual''s biggest f-ck up is the HTML code for the items in  
the manual. (Even M$ Frontpage beta1 couldn''t write that bad  
HTML ;-) ) The point here though is that there''s no easy way to  
access the information programmatically. 
So instead of lumping one whole entry into a single textbox (with  
basic RedCloth formatting etc) you should split it up in smaller  
chunks instead. Sort of like this:
     -- Function/Method Name
     -- F/M Syntax
     -- F/M Description (short desc of what it does & any quirks)
     -- Extended Description with clearly divved and named content   
within it. ie Notes, Tips & Examples are within their own named
div''s
         and that they are named/numbered accordingly, so we would  
have <div id="example1"> and <div
id="note_something">
     -- See Also (links to related F/M''s or info )

That way someone like me will be able to repurpose the info for  
something like this [ http://imediatec.co.uk/tm/phpcc/ ] and that''s  
bloody hard to do if you have badly structured data to work with.   
Also if you separate content out in smaller chunks you can rewrite it  
in any other format easily as well, such as into XML.

If you have any questions or comments I''d happily help you answer  
them if I can.


Kind regards,

Mats

----
"TextMate, coding with an incredible sense of joy and ease"
- www.macromates.com -




_______________________________________________
Rails mailing list
Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
http://lists.rubyonrails.org/mailman/listinfo/rails

On Jul 15, 2005, at 3:57 AM, Mats Persson wrote:
>
> On 14 Jul 2005, at 21:45, Ben Robison wrote:
>> http://raildock.mytechsupport.com/  It''s got some pretty cool
>> search functionality, and allows registered users to add snippets,  
>> etc.  to the documentation.  You may not find much of these custom  
>> comments since it''s only been around for 4-5 days now, but
this
>> may be something like what you''re looking for.  It''s
certainly
>> prettier that the http://www.php.net/manual ;-)
>
> Had a look at RailDock, but although it might be good down the road  
> it sure does not help me today. ( only 2 items right now ?! )
>
You  must have caught it last night during the upgrade.
> As for prettier than PHP.net''s manual. Well, pardon me for saying
> this, but that''s about as important to me - or any other real
users
> - as getting paid for my work in new crisp clean notes (rather than  
> wrinkly used ones).  I don''t care, I just want to get paid the
full
> amount.
>
This is a non-profit organization.  :)
> PHP.net''s manual has many flaws, but if you haven''t used
it
> extensively then you''ve missed one of the best features on the
web.
> 90% of the time it''s clear, concise and precise and answers your  
> question. That''s the way any manual should be ! (if you are  
> ideologically opposed to PHP, then wake up and ask some questions  
> from it and get the answers immediately and conveniently)
>
We''ll need people to continue contributing (especially people like  
you who (a) care about documentation and (b) are qualified to write  
clear and precise answers to your questions because you know better  
than anyone what a newbie finds difficult, hard to understand, or  
misdirecting) and the Rails documentation will get there.
> Duane, while you''re still developing the stuff please take these  
> comments onboard:
>
> -- although looks good certainly is nice, it''s NOT the most  
> important factor. Actually it''s pretty far down the list.
Usability
> and ease of use (which is really clarity of structure and design)  
> scores 100 times higher.
>
I''m sorry you had a bad experience.
> --  the php manual supports this:  www.php.net/<NAME_OF_FUNCTION>    
> which redir''s to the relevant manual page, or in the case of a
non-
> exact match shows you a list of possibles.  (there are several  
> entry points for this, so it''s not only in the root of site)
> This is a brilliant implementation, and you should really do the  
> same !!
>
http://raildock.mytechsupport.com/ri/<NAME OF CLASS OR FUNCTION NAME>
> -- the php manual''s biggest f-ck up is the HTML code for the items
> in the manual. (Even M$ Frontpage beta1 couldn''t write that bad  
> HTML ;-) ) The point here though is that there''s no easy way to  
> access the information programmatically. 
> So instead of lumping one whole entry into a single textbox (with  
> basic RedCloth formatting etc) you should split it up in smaller  
> chunks instead. Sort of like this:
>     -- Function/Method Name
>     -- F/M Syntax
>     -- F/M Description (short desc of what it does & any quirks)
>     -- Extended Description with clearly divved and named content   
> within it. ie Notes, Tips & Examples are within their own named
div''s
>         and that they are named/numbered accordingly, so we would  
> have <div id="example1"> and <div
id="note_something">
>     -- See Also (links to related F/M''s or info )
>
This might be more difficult to do than it seems.  The content for  
the documentation is coming from the source code--so it is as it is.   
If you have some ideas (feel free to open up the RailDock source to  
see how things are being done currently) then please do share.

Duane Johnson
(canadaduane)




_______________________________________________
Rails mailing list
Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
http://lists.rubyonrails.org/mailman/listinfo/rails

On Thursday 14 July 2005 22:31, Mats Persson wrote:
> I am not a CS guy, but I managed to pick up PHP because it was easy  
> to learn and had good easy to digest information, and I''m hoping
for
>   the same here with RoR & Ruby.
Read the Rails source code! At least give it a try. The code is not 
always easy to understand, but it''s well worth the effort.
You''ll be an
ever so slightly better programmer afterwards.

Michael

-- 
Michael Schuerig                  There is no matrix,
mailto:michael-q5aiKMLteq4b1SvskN2V4Q@public.gmane.org        only reality.
http://www.schuerig.de/michael/   --Lawrence Fishburn

On 7/15/05, Michael Schuerig
<michael-q5aiKMLteq4b1SvskN2V4Q@public.gmane.org>
wrote:
> Read the Rails source code! At least give it a try. The code is not
> always easy to understand, but it''s well worth the effort.
You''ll be an
> ever so slightly better programmer afterwards.
Yeah, unless you''re brand-new to Ruby and don''t have much/any
practical software architecture experience or CS education. With all
respect, this suggestion totally misses the point of the discussion
that preceded it.

- DD

I''m sorry, but I just had to respond to this.

On 15 Jul 2005, at 18:45, Michael Schuerig wrote this in response to  
my post:
> On Thursday 14 July 2005 22:31, Mats Persson wrote:
>> I am not a CS guy, but I managed to pick up PHP because it was  
>> easy to learn and had good easy to digest information, and I''m
>> hoping for the same here with RoR & Ruby.
>
> Read the Rails source code! At least give it a try. The code is not  
> always easy to understand, but it''s well worth the effort.
You''ll
> be an ever so slightly better programmer afterwards.
To which on 16 Jul 2005, at 01:37, David Demaree responded with such  
great clarity and intelligence:
> Yeah, unless you''re brand-new to Ruby and don''t have
much/any
> practical software architecture experience or CS education. With  
> all respect, this suggestion totally misses the point of the  
> discussion that preceded it.
The main point that Michael Schuerig and seemingly some others  
haven''t grep''d, is this:

Om jag inte förstår språket, dess struktur, grammatik och nyanser,  
hur kan jag då läsa något och förstå det på rätt sätt ?

Oh, most of you didn''t understand that. Hmm, maybe you should read  
some Swedish writing then and eventually you will understand it.

The above 2-3 sentences ought to have irritated someone, and that was  
the point !  No logically thinking individual trying to learn a new  
foreign language would set out reading that language and hoping to  
extract meaning, logic and nuances from just reading it. The KEY to  
learning and understanding that new language is something like a  
<ForeignLanguage>/<YourNativeLanguage> dictionary/phrase book. In  
other words a succinct and structured reference point where you can  
quickly, efficiently and reliably look up that word that is not  
understood by you.

Think about the above for 2 seconds, and you will clearly see where  
your logic fails fundamentally, Michael.  IF you can''t after that,  
then get the hell away from the computer and start learning a new  
language ;-)

And yes, I have read through much of the source code, I have looked  
at/read things. My problem is not one of laziness, but rather that my  
mind is damn good at remembering that I have seen (read) something,  
but I can''t fully remember what and where. When it comes to PHP I can  
just go to the online manual and search for it, but I can''t do the  
same with the Ruby/RoR stuff at the moment can I.

Topic closed.

Kind regards,

Mats

----
"TextMate, coding with an incredible sense of joy and ease"
- www.macromates.com -

On Saturday 16 July 2005 11:11, Mats Persson wrote:
> I''m sorry, but I just had to respond to this.
No, you''re not sorry at all. As little as David below means what he 
writes "with all respect". These are just phrases.
> On 15 Jul 2005, at 18:45, Michael Schuerig wrote this in response to
>
> my post:
> > On Thursday 14 July 2005 22:31, Mats Persson wrote:
> >> I am not a CS guy, but I managed to pick up PHP because it was
> >> easy to learn and had good easy to digest information, and
I''m
> >> hoping for the same here with RoR & Ruby.
> >
> > Read the Rails source code! At least give it a try. The code is not
> > always easy to understand, but it''s well worth the effort.
You''ll
> > be an ever so slightly better programmer afterwards.
>
> To which on 16 Jul 2005, at 01:37, David Demaree responded with such
>
> great clarity and intelligence:
> > Yeah, unless you''re brand-new to Ruby and don''t have
much/any
> > practical software architecture experience or CS education. With
> > all respect, this suggestion totally misses the point of the
> > discussion that preceded it.
>
> The main point that Michael Schuerig and seemingly some others
> haven''t grep''d, is this:
>
> Om jag inte förstår språket, dess struktur, grammatik och nyanser,
> hur kan jag då läsa något och förstå det på rätt sätt ?
>
> Oh, most of you didn''t understand that. Hmm, maybe you should read
> some Swedish writing then and eventually you will understand it.
If I were to learn Swedish it would indeed be a good idea to read 
Swedish texts at an appropriate(!) level of complexity.
> The above 2-3 sentences ought to have irritated someone, and that was
> the point !  No logically thinking individual trying to learn a new
> foreign language would set out reading that language and hoping to
> extract meaning, logic and nuances from just reading it. The KEY to
> learning and understanding that new language is something like a
> <ForeignLanguage>/<YourNativeLanguage> dictionary/phrase book.
In
> other words a succinct and structured reference point where you can
> quickly, efficiently and reliably look up that word that is not
> understood by you.
A programming language is a very different beast from a natural 
language. For one thing, variability among programming languages is 
minuscule in comparison. Particularly, if you leave out functional, 
logic and other "fringe" languages and concentrate on the mainstream 
core of OOP exemplified by C++, Java, Ruby, Python alike. That''s more 
like learning to understand a new dialect of your native tongue than 
learning an entirely new natural language, say Hungarian when you only 
know a germanic language.
> And yes, I have read through much of the source code, I have looked
> at/read things.
Then what are you complaining about? Did it hurt? Did you learn 
something? I hope so. You may note that I didn''t write that people 
should use the source code as the sole documentation and that there''s 
no need for anything besides, such as high-level explanations and 
examples. So far I have not seen a valid objection against reading the 
source code.

You might say that people who are just learning to program, or people 
who are trained as designers don''t stand a chance understanding the 
code. Very true. They won''t be able to appreciate every detail and may 
not get how things hang together. I grant all that. In my opinion 
people with very little programming knowledge have more pressing things 
to do than try to build web apps with Rails. They need to get some 
basics, by reading the PickAxe book, say (for best results, put "The 
Pragmatic Programmer" alongside). Who said programming is easy? It is 
not. People who expect it to be and try to learn it along the way -- 
well, they''re in for a surprise. Or, worse, they don''t notice
their
shortcomings and produce bad software.

Let me repeat that I''m not opposed to any more documentation Rails can 
get. Nevertheless, it also bears repeating that there already are 
several ways to learn about Rails. Among them is reading the source 
code. Don''t forget about it.
> Topic closed.
If you say so...

Michael

-- 
Michael Schuerig                  There is no matrix,
mailto:michael-q5aiKMLteq4b1SvskN2V4Q@public.gmane.org        only reality.
http://www.schuerig.de/michael/   --Lawrence Fishburn

This is completetly true. You can learn a great deal from reading  
source code, and Ruby is particularily readable comapred to other  
programming languages.

So I don''t understand what the fear (is it that?) of diving into it  
is about. I don''t get it. The main point that Mats Persson and  
seemingly some others haven''t grep''d, is this: people learn
things
differently.

Thomas

Am 16.07.2005 um 11:50 schrieb Michael Schuerig:
> Let me repeat that I''m not opposed to any more documentation Rails
can
> get. Nevertheless, it also bears repeating that there already are
> several ways to learn about Rails. Among them is reading the source
> code. Don''t forget about it.

On 16 Jul 2005, at 10:50, Michael Schuerig wrote:
> On Saturday 16 July 2005 11:11, Mats Persson wrote:
>> I''m sorry, but I just had to respond to this.
> No, you''re not sorry at all. As little as David below means what
he
> writes "with all respect". These are just phrases.
I was never intentionally personal !  And yes, i''m sorry for  
extending a subject like this beyond what it was originally intended  
to be. This is getting too far away from the main purpose of this ML  
in my mind.

I am actually trying very hard to be respectful and courteous, so  
don''t take my failures in that as something negative towards you or  
anyone else. IF I wish to be rude/angry/insulting I will be so in  
clear terms. I''m a straight talking kind-of-guy.

> If I were to learn Swedish it would indeed be a good idea to read  
> Swedish texts at an appropriate(!) level of complexity.
Yes, i agree to a certain extent, but are you therefore saying that  
the Rails code is of that appropriate level for me (and other  
newbies) ? Surely not, right ?

> A programming language is a very different beast from a natural  
> language. For one thing, variability among programming languages  
> is  minuscule in comparison. Particularly, if you leave out  
> functional, logic and other "fringe" languages and concentrate on
> the mainstream core of OOP exemplified by C++, Java, Ruby, Python  
> alike. That''s more like learning to understand a new dialect of  
> your native tongue than  learning an entirely new natural language,  
> say Hungarian when you only know a germanic language.
OK, trying to address this point carefully and precisely: (will most  
likely fail)

1.  Yes, programming languages are generally more similar in nature  
than natural languages. That does not make them any easier to  
**fully** understand as new comers.

2. I am NOT a programmer. I know PHP, HTML, CSS, JS/ActionScript,  
Lingo and basic regex & shell (bash) and that''s where my knowledge
in
"programming languages" ends. That has not prevented me from doing  
things in PHP that to some would seem fairly advanced and has  
included OOP principles.

3. Ruby as a new dialect to my (PHP/HTML/CSS/JS) native tongue. Yes,  
there are similarities, but there are also differences.  In my  
original post **which is the embracing context that this is all  
written within** I was simply trying to ask for a dictionary that  
translated the words that i could not understand. A reference point  
that i could consult when there was a question/problem/ambiguity.

>> And yes, I have read through much of the source code, I have  
>> looked at/read things.
> Then what are you complaining about? Did it hurt? Did you learn  
> something? I hope so.
Michael, please point out where I was complaining ? Where I said it  
hurt ? Where I said I didn''t learn something ?

> You may note that I didn''t write that people should use the source
> code as the sole documentation and that there''s no need for  
> anything besides, such as high-level explanations and examples.
Yes, noted.

> So far I have not seen a valid objection against reading the source  
> code.
How about this ?
-- If as you read said code you encounter a word/structure/symbol/ 
something that you don''t understand - and cannot easily identify  
through reference material - then you will fail to fully understand  
that part of the code.
-- Failing to fully understand the code, can/will lead to  
misunderstandings and generally result in bad code.

> You might say that people who are just learning to program, or  
> people who are trained as designers don''t stand a chance  
> understanding the code. Very true. They won''t be able to
appreciate
> every detail and may not get how things hang together. I grant all  
> that.
Good, so we are both understanding the same thing then, and you will  
agree that what Ruby/RoR is missing is a succinct and structured  
reference point where you can quickly, efficiently and reliably look  
up that word/structure/symbol/concept/something that is not fully  
understood. (?)

> In my opinion people with very little programming knowledge have  
> more pressing things to do than try to build web apps with Rails.  
> They need to get some basics, by reading the PickAxe book, say (for  
> best results, put "The Pragmatic Programmer" alongside).
OK, we''re hitting this from two opposed directions it seems.  It is  
''people'' (= web developers) like me that often have pressing
needs to
build **web solutions** for real clients.  As is always the case, we  
need to do so quickly, efficiently and solidly. Due to the efforts of  
DHH, Justin French and a few others, people like me (possibly from  
the "great unwashed horde of ''non-programmers''")
have started to give
RoR our attention.

As for basics, I think I''ve got most of those, but I still only asked  
for a simple thing, a good reference point for information.

> Who said programming is easy? It is not. People who expect it to be  
> and try to learn it along the way -- well, they''re in for a  
> surprise. Or, worse, they don''t notice their shortcomings and  
> produce bad software.
No one said that. You probably find it much easier than I do, and  
that''s why you might take it for granted, whereas I - and others -  
have to struggle to do it.  By having a good solid, efficient and  
reliable reference source with good, detailed, comprehensive and  
accurate information you make it easier to program for everyone -  
beginners to professionals - and you can begin to address the issues  
of bad code being produced.

> Let me repeat that I''m not opposed to any more documentation Rails
> can get. Nevertheless, it also bears repeating that there already  
> are several ways to learn about Rails. Among them is reading the  
> source code. Don''t forget about it.
Good, so you can (will ?) help the community create that reference  
point then and improve the wiki stuff, which is often OK, but  
sometimes takes things for granted or misses out steps or fails to  
explain why.

>> Topic closed.
> If you say so...
OK, you got me, I was wrong. Maybe I''m right this time ?

Peace be within us all.


Kind regards,

Mats

----
"TextMate, coding with an incredible sense of joy and ease"
- www.macromates.com -

On 16 Jul 2005, at 11:07, Thomas Fuchs wrote:
> Am 16.07.2005 um 11:50 schrieb Michael Schuerig:
>> Let me repeat that I''m not opposed to any more documentation
Rails
>> can get. Nevertheless, it also bears repeating that there already  
>> are several ways to learn about Rails. Among them is reading the  
>> source code. Don''t forget about it.
> This is completetly true. You can learn a great deal from reading  
> source code, and Ruby is particularily readable comapred to other  
> programming languages.
Yes, I''ve got the absolute majority of my understanding various  
languages from reading source code, and yes Ruby/RoR looks  
particularly easy at times, but there are still stumbling blocks, and  
I simply asked and tried to argue for a single good reference point  
where I could on my own and in an efficient, reliable and clear way  
overcome that stumbling block.

Am I hammering home my original point enough ? ;-)

> So I don''t understand what the fear (is it that?) of diving into
it
> is about. I don''t get it.
I don''t have any fear of reading source code, if that''s what
you are
questioning. If I have any ''fear'' about anything related to
Ruby/RoR
is to waste my time, learn the wrong things, produce bad code that  
causes failures and then needs to be identified and changed.

I know my PHP stuff, and I''m very comfortable with it. I''ve
created
my own framework and it''s good in my mind, but IF I can use something  
like RoR to do more in less time like Justin French/DHH claims, then  
I would want to do so.

I joined this ML and my first post was asking for a good reference  
point. Some would say I''m knee deep already ;-)

> The main point that Mats Persson and seemingly some others haven''t
> grep''d, is this: people learn things differently.
:-)   Don''t worry, Thomas, I grep''d that one a long time ago! 
I was
just questioning whether everyone else had after having possibly  
misunderstood Michael''s post, and it came out a bit wrong. My
apologies.


Kind regards,

Mats

----
"TextMate, coding with an incredible sense of joy and ease"
- www.macromates.com -

On 7/16/05, Mats Persson <mats-uGq4Pdis5ybkYMGBc/C6ZA@public.gmane.org>
wrote:
> Yes, i agree to a certain extent, but are you therefore saying that
> the Rails code is of that appropriate level for me (and other
> newbies) ? Surely not, right ?
I agree.  All the Ruby docs I''ve seen to this point leave much to be
desired, especially after using the php.net manual for many years. 
Some Ruby doc pages I''ve seen online don''t even have content
on them,
you click a link and it loads a fairly empty page.  I thought my
browser was broken at first, then I realized this was the norm with
Ruby docs.

Having recently acquired a copy of the Pickaxe I am making due.  ri is
helpful but only goes so far when you don''t know a lot of class and
function names yet.


-- 
Greg Donald
Zend Certified Engineer
MySQL Core Certification
http://destiney.com/

>> The main point that Mats Persson and seemingly some others
haven''t
>> grep''d, is this: people learn things differently.
>
> :-)   Don''t worry, Thomas, I grep''d that one a long time
ago!  I
> was just questioning whether everyone else had after having  
> possibly misunderstood Michael''s post, and it came out a bit
wrong.
> My apologies.

No problem :)

Anyway, if you say you know PHP/Actionscript or whatever, then you  
are a programmer.

If you''re new to Ruby, check out http://poignantguide.net/ruby/ and  
of course the "Programming Ruby" book.
The best way to learn Rails is IMHO: Just dive into it, follow the  
tutorials and learn-as-you-go, asking question on the IRC channel.

Thomas

On Jul 16, 2005, at 9:05 AM, Greg Donald wrote:
> Some Ruby doc pages I''ve seen online don''t even have
content on them,
> you click a link and it loads a fairly empty page.  I thought my
> browser was broken at first, then I realized this was the norm with
> Ruby docs.
>
> Having recently acquired a copy of the Pickaxe I am making due.  ri is
> helpful but only goes so far when you don''t know a lot of class
and
> function names yet.
I concur, and FWIW: For learning Ruby, in my opinion, you can''t  
improve upon the Pick Axe. But in the context of Rails, Ruby is just  
the grammar. My mother is a typist for court reporters, and while she  
has no medical training she is often required to provide word- 
accurate transcripts of some very arcane terminology. She does it  
with the help of some reference manuals.

The Rails APIs have their own vocabulary, and while the source code  
thing is great if you can get it, it doesn''t solve the problems of:

* Usefulness to brand-new Ruby/Rails coders
* Easy searchability
* Being able to see the code in action (through examples) to see how  
it is practically, not theoretically, applicable to whatever problem  
you''re working

Greg brings up another problem with the WIki format of most of the  
docs on the Rails site (and many general Ruby sites): it''s extremely  
common for someone to contribute not just poorly written  
documentation, but blank pages serving as placeholders for manuals  
that will never be completed. Which is frustrating, and reinforces in  
us non-CS coders the idea that in order to know/learn Rails you have  
to spend hours futzing around with it. A lot of us don''t have that  
kind of time to gain experience with a new framework by  
experimentation or browsing the source code. We need easy, direct  
access to digestible information that can be easily applied to the  
problem at hand.

Of course, it wouldn''t serve anyone to perpetuate this discussion  
without flaming Michael again:
> On Saturday 16 July 2005 11:11, Mats Persson wrote:
>
>> I''m sorry, but I just had to respond to this.
>
> No, you''re not sorry at all. As little as David below means what
he
> writes "with all respect". These are just phrases.
You''re right, sir: they are just phrases. Phrases in English. A  
language we understand. If you were suggesting that we look at the  
source code for _Hamlet_ or _A Farewell to Arms_ or _Jurassic Park_,  
I would say, "Sure! No problem!" You, however, were suggesting that  
Mats and other new Ruby/RoR coders should look at the Rails source  
code, written in Ruby, in order to learn how to code using Rails and  
Ruby, which is sort of like being one of those monkeys at the  
thousand typewriters on his first day on the jorb.

I won''t say "I''m sorry if you felt personally
insulted" because
_those_ would be just words. But when I write "with all respect",  
i.e. for your opinion, intelligence and clearly superior ability to  
grok the Rails source code, I do mean it with sincerity. I don''t have  
to agree with you in order to respect you, and Mats (correct me if  
I''m wrong) would not have said he was sorry, i.e. to argue with you,  
if he didn''t respect your viewpoint.

- D D

Please contribute! The Wiki is there for your contributions, too (be  
sure to leave a question behind on the corresponding wiki page, so  
someone might just answer it; note the RSS feed for Wiki updates). :)

Everything is welcome, especially documentation. If you solve some  
problem, please do update the wiki, and consider putting up a comment  
on http://raildock.mytechsupport.com/

This is the only way the next time someone hits the problem  
documentation that solves this is there.

Also, there is one book out there now, and several in the pipeline.

Thomas


Am 16.07.2005 um 20:00 schrieb David Demaree:
> Greg brings up another problem with the WIki format of most of the  
> docs on the Rails site (and many general Ruby sites): it''s  
> extremely common for someone to contribute not just poorly written  
> documentation, but blank pages serving as placeholders for manuals  
> that will never be completed. Which is frustrating, and reinforces  
> in us non-CS coders the idea that in order to know/learn Rails you  
> have to spend hours futzing around with it. A lot of us don''t have
> that kind of time to gain experience with a new framework by  
> experimentation or browsing the source code. We need easy, direct  
> access to digestible information that can be easily applied to the  
> problem at hand.

On Saturday 16 July 2005 20:00, David Demaree wrote:
> If you were suggesting that we look at the  
> source code for _Hamlet_ or _A Farewell to Arms_ or _Jurassic Park_,
>   I would say, "Sure! No problem!" You, however, were suggesting
that
> Mats and other new Ruby/RoR coders should look at the Rails source
> code, written in Ruby, in order to learn how to code using Rails and
> Ruby, which is sort of like being one of those monkeys at the
> thousand typewriters on his first day on the jorb.
Never did I recommend to learn Ruby/Rails from nothing but Rails source 
code. Let me spell it out more thoroughly.

In my opinion, people with no programming experience at all should not 
start out trying to create a web app with Rails. People who have never 
used Ruby before should not do so either. They should do themselves a 
favor and learn the basics of programming in Ruby first -- most likely 
using the appropriately titled book.

Then, for people who feel comfortable with Ruby and the basics of Rails, 
if they get to an impasse where the available documentation does not 
help, then, please, consider looking at the Rails source code. Also, if 
anyone''s curious just how things work it''s a good idea to read
the
source. And don''t forget there''s always the option of asking
on this
list! Incidentally, that''s just what I''m doing, too.

Michael

-- 
Michael Schuerig               Most people would rather die than think.
mailto:michael-q5aiKMLteq4b1SvskN2V4Q@public.gmane.org                          
In fact, they do.
http://www.schuerig.de/michael/                      --Bertrand Russell