[aida] Aida comprehensive documentation: a newbie experience

Janko Mivšek janko.mivsek at eranova.si
Tue Jul 26 00:09:29 CEST 2011


Hi Offray,

Good anecdote about "she is my girlfriend, but she don't know", I need
to remember that one, hehe.

About tutorial: I corrected the second code snippet, it was actually
ambiguous and I hope now is more clear, also because three methods are
announced in paragraph above.

About Spanish translation: it is certainly outdated and needed an
upgrade, Are you willing to upgrade it? We can move it to our website,
so you can edit it directly here? Translation was done by Giuseppe Luigi
Punzi glpunzi na lordzealon.com, maybe we can ask him too?

Also, the ToDo example is an opportunity for another tutorial, are you
wiling to write it according to your ideas from elsewhere? This will
really be something! Then we can just refresh and comlete the
Programmers manual and this could be quite some docs then. Then a book,
well ... :)

About jQuery: I agree that smalltalkized jQuery is a nice Seaside
feature and I'm thinking about adding to Aida, but as add-on, not the
necessary feature. Specially not for Ajax. Ajax is namely completely
integrated in Aida and doesn't need jQuery. Whole JS needed is only 4K
vs. how many is jQuery? In any case you need to study that ToDo example,
let me send you instructions, privately for now, because it is yet to be
polished a bit for a public release.

And of course, more feedback, more feedback :)

Best regards
Janko

S, Offray Vladimir Luna Cárdenas piše:
> 
> Hi Janko,
> 
> El 24/07/11 14:31, Janko Mivšek escribió:
>> Hi Offray,
>>
>> Welcome to the list and thanks a lot for your thoughts, that's what we
>> need and this is what give us encouragement to be better and better!
> 
> Thanks,
> 
>> About documentation: yes, that is major Aida weakness and I don't know
>> exactly how to solve it. I'm simply better in thinking and coding, not
>> in writing, so any help here is really appreciated. We will soon have a
>> ToDo example, which shows all that bleeding edge Aida features for
>> building so called Single page (SP) applications, as an addition to
>> traditional web apps shown in current tutorial.
>>
>> Support for a combination of traditional and SP apps will put Aida on
>> the web frontiers, just that without documentation no-one will know
>> that. Yes, you are very right, lack of docs is also a reason for a lack
>> of visibility of what all Aida is capable.
> 
> 
> Agree. This situation remembers a local joke about the seeing the woman 
> of your dreams and saying to your friends "she is my girlfriend, but she 
> don't know" and the joke is not about confidence that she _will_ be your 
> girlfriend, but about _being_ now and not knowing. Aida can be pushing 
> the envelope and exploring the frontier of the web, but without proper 
> documentation, is like if the woman of your dreams doesn't know about 
> being your girlfriend. Today I tried the tutorial again, using it in 
> pair with the Spanish translation. I found some errors in my previous 
> implementation, but still I have not joy and I have found just a 
> different error. The way I found the errors was seeing the subtle 
> differences between Spanish and English tutorial. In the first one you 
> have a typographical convention for method names, so you understand that 
> this:
> 
> initAddresses
>               addresses := OrderedCollection new
>           addresses
>              addresses isNil ifTrue: [self initAddresses].
>             ^addresses
> 
> is really two separate methods: initAddresses and addresses (yes, silly 
> me that would have to notice at first, but with the typographical 
> convention was really easy to find, even without a deeper understanding 
> of Smalltalk). Also while the English tutorial say things like:
> 
> "add a class method for fast ADemoAddress creation:"
> 
> The Spanish say:
> 
> "
> Añade un método de clase para creación rápida de ADemoAddress (recuerda 
> que debe ser de clase no de instancia. Debes presionar antes Class en el 
> panel de la clase, antes de crear el método)
> "
> 
> which translates:
> 
> "
> Add a class method for fast ADemoAddress creation (remember that it 
> should be a class method, not an instance one. You should press Class in 
> the panel of the class before creating the method).
> 
> That part in the parenthesis can be a real difference for a newbie, but 
> even in that case, I still have to decipher:
> 
> "create an initialize method, accessors for the ADemoAddressBook instvar 
> addresses and addition method, which will also set a back reference from 
> address to its parent, the address book. This back reference will come 
> handy later for navigation from address page back to address book:
> "
> And I just populated the browser with the following code after that 
> paragraph, but when I get the Error:
> 
> ADemoAddress(Object)>>doesNotUnderstand: #firstName
> 
> I start to wonder if I have deciphered the paragraph well.
> 
> With the Seaside tutorial the terms are explained at length, for example:
> 
> "
> But first let us discover what is necessary:
> 
> Every newly-created component is inherited from WAComponent.
> 
> Every component needs a method called #renderContentOn: accepting a 
> renderer.
> 
> Components that shall be root components need a class method called 
> #canBeRoot.
> 
> So what does that mean?
> 
> WAComponent is the basic component provided by Seaside. That means every 
> visible component inherits from WAComponent. There are many more 
> components you can use, like WATask, but more on that later. For now, 
> just keep WAComponent in mind.
> 
> While inheritance is one requirement, the rendering part is another. To 
> generate HTML code from within your Smalltalk code, you need a renderer. 
> WAComponent ensures that the method #renderContentOn: is called. By 
> giving the method a renderer you have access to all WACanvas methods 
> provided by Seaside. So let us keep that theoretical stuff in mind and 
> create the first component of our ToDo Application
> "
> 
> So you're creating a mental model of how Seaside works at the same time 
> that you're going to the tutorial (that's why is a 12 chapters, 212 
> pages tutorial).
> 
> 
>> About Smalltalk knowledge for newbie: is Seaside HPI tutorial good even
>> for a complete non-Smalltalker? How they achieved that, AFAIK they don't
>> learn Smalltalk basics in this tutorial?
> 
> No, the HPI tutorial is it not good for a complete non-Smalltalker, but 
> they point to really good sources of documentation for newbies as 
> complementary/parallel readings (is what I'm doing) at the same time 
> thay provide this mental model while they advance in the tutorial. You 
> can find things like this in the introductory chapters (I would like to 
> point the specif part, instead of pasting large chunks here, but may be 
> the ugly urls of Seaside don't work for that, so there it comes, without 
> the embedded links):
> 
> "
> Requirements
> 
> 
> The Seaside Tutorial has mainly been made for people with basic 
> knowledge of object-oriented programming especially with Smalltalk, but 
> it is suitable for others as well. We try to reduce the fundamental 
> knowledge on the elements demanded here. If you have suggestions for 
> better descriptions of any part, please send us your feedback.
> 
> Recommended Knowledge
> 
> Object-oriented programming should be known well enough that words like 
> class, object, inheritance or reuse do not put question marks in your 
> eyes. Here, no links are given, just because there is a wealth of 
> standard literature and we do not want to prefer any of it.
> 
> Smalltalk (as a programming language) has to be known well, because 
> Seaside itself only exists in this language. Should you have any 
> problems with it, have a look at the following link:
> 
> Smalltalk Free Books
> 
> Squeak is used as the Smalltalk environment of choice in this tutorial, 
> but Seaside has also been implemented on other common Smalltalk 
> platforms (see the corresponding documentation). For more help with the 
> treatment of Squeak, the following links are quite helpful. However, we 
> try to use particularities of the Squeak Smalltalk dialect as seldom as 
> possible
> 
> Squeak by Example (ebook)
> 
> Squeak Web site
> "
> 
> They have chosen also a default environment for explaining Seaside, the 
> one that is most while available and without hidden cost: Squeak (Pharo 
> would work also). So, I think that this kind of default experience in a 
> widely used environment should be part of the tutorial. I suggest to use 
> Pharo One Click Experience as the environment for the construction of 
> such comprehensive documentation, with mentions, short references and 
> explanations about other environments (for example installing on 
> different Smalltalk flavors).
> 
>> About our web frameworks to form a strong front and compete with others,
>> yes, this is a very stated goal and specially with Jtalk work by Nicolas
>> Petton for client-side web apps we can actually "penetrate" to outside
>> word more deeper. JavaScript is a king on client-side but it was not
>> designed for programming at large, while Smalltalk is. We have therefore
>> a chance here and both Aida and Iliad have plans/working intensively on
>> that area.
> 
> Jtalk is really awesome and I hope this integration going deeper and 
> showing the potential of Smalltalk in the web (by the way, ¿why the 
> split of people between Iliad and Aida?). One of the things that is most 
> impacting after installing and running Seaside is the integration with 
> JQuery and JQueryUI, showing parallel demos of them and the Seaside code 
> for getting that working. Knowing that you don't have to learn another 
> language to get that dynamic behavior on web pages with modern and 
> widely used javascript library is an impressive selling point at a first 
> glance. Aida demos of integration with Javascript and Ajax seems steps 
> away in that sense, and could learn from the way that Seaside makes the 
> integration with JQuery available (seems that this kind of integration 
> of JQuery and Aida is not available yet)
> 
>> About persistence: you probably already noticed that Smalltalkers tend
>> to avoid RDBses as much as possible. One reason is that image itself is
>> kind of a database and image based pesistence works surprisingly well
>> for small to middle sized projects. And for larger we have a Gemstone
>> with which we can scale up to the sky :) It is true that it is not open
>> source, but this actually don't count much in otherwise small Smalltalk
>> community. And free GS version is more than enough for a quite large
>> systems.
> 
> Yes. Image based persistence is, for me, another selling point of 
> Smalltalk. Carrying your One Click Experience in a thumb drive and 
> knowing that you can run it everywhere with all your data saved there is 
> key for my intended project. More in a another mail.
> 
>> So, ok, let me finish too for now and rather publish a ToDo example
>> ASAP, so that we will have a foundation for some more docs .. :)
> 
> Ok. But as I teach teenagers and adults about informatics, I wonder, as 
> they do, about the use in "the real world" of this kind of apps. I mean: 
> there is any people using the ToDo app for something besides explaining 
> how the framework works, and, if this is the case, why we don't know of 
> public sites like "remember the milk" powered by them. I think that we 
> need another kind of examples in the tutorial, more in concordance with 
> what social web has to offer and the problems we can solve there, but 
> this will be topic of the mentioned "other mail"
> 
> 
>> Thanks again and keep posting more!
>>
>> Janko
> 
> 
> Thanks to you Janko and to this helpful community. The more I can learn 
> about Seaside, the more I will try to give feedback to Aida and 
> hopefully help with documentation, not only in constructive criticism 
> but also in some writing.
> 
> Cheers,
> 
> Offray
> _______________________________________________
> Aida mailing list
> Aida na aidaweb.si
> http://lists.aidaweb.si/mailman/listinfo/aida

-- 
Janko Mivšek
Aida/Web
Smalltalk Web Application Server
http://www.aidaweb.si


More information about the Aida mailing list