[Newbies] more of a general smalltalk question

[smith02243]

cdrick wrote:
> 
> An idea: learning from source code could be documented too by small
> "how-to".
> 
> For instance to understand how sandstonedb works (which is already
> well documented thanks to Ramon) we could imagine that:
> 
> HOW-TO-LEARNING SDActiveRecord  "file oodb persistency inspired by
> ruby activerecord framework"
> -restoring persistent objects
> 
> "put a self halt in SDActiveRecord class>>warmUp" (wich is called at
> startup for activerecord like objects,
> "save and quit". then
> "start again the image".
> This opens a debugger that will help you understand how persistent
> objects are restored... Debugger will open on Mock classes that exists
> for test reasons. It will also open on all your active records
> (subclasses of SDActiveRecord)
> 
> etc etc...
> 
> This is a small documentation effort that would be precious. We could
> also illlustrate with videos which if we had standard tools could be
> done without too much effort (I mean less than getting all done with
> text only)...
> 
> see: http://www.squeaksource.com/SandstoneDb/
> 
> My 2 cents ;)
> 
> Cédrick
> 
> _______________________________________________
> Beginners mailing list
> Beginners at lists.squeakfoundation.org
> http://lists.squeakfoundation.org/mailman/listinfo/beginners
> 
> 

I strongly agree that the source code must be supplemented with something.
GNU Smalltalk has excellent library documentation. Admittedly, in Squeak
it's easier to browse the source-code thanks to Squeak's GUI, yet proper
documentation would still be a huge boon to development, especially for
neophytes. 

Furthermore, in Squeak by Example there's this quote by Alan Knight:

   Try not to care. Beginning Smalltalk programmers often
   have trouble because they think they need to understand
   all the details of how a thing works before they can use
   it. This means it takes quite a while before they can 
   master Transcript show: 'Hello World'. One of the great leaps
   in OO is to be able to answer the question “How does
   this work?” with “I don’t care”.

We cannot really take that advice seriously if we force users to browse
source code whilst building their applications. This is especially
detrimental to new users, who generally want to start building applications
as soon as possible, and care little about implementation. If they're forced
to care about implementation I would guess they'd prefer to use something
else, something with better documentation and a rival set of libraries,
Python for example.
-- 
View this message in context: http://www.nabble.com/more-of-a-general-smalltalk-question-tp18288372p18352304.html
Sent from the Squeak - Beginners mailing list archive at Nabble.com.