[aida] Aida comprehensive documentation: a newbie experience

Offray Vladimir Luna Cárdenas offray at riseup.net
Mon Jul 25 18:33:41 CEST 2011

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!


> 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 

              addresses := OrderedCollection new
             addresses isNil ifTrue: [self initAddresses].

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 

Components that shall be root components need a class method called 

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):


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 

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.



More information about the Aida mailing list