Aida comprehensive documentation: a newbie experience

> Hi all and thanks for Aida.
>
> This will be a long mail talking about my initial lectures as a newbi on
> Aida/Smalltalk and development and what brings me and keeps me here, so
> I hope to stay with me
>
> As a newbie, I have been wondering about using web2py, Seaside or Aida
> for a small project. It seemed for a while, that Aida was the proper way
> to go, but I'm was little worried for the lack of documentation. After
> trying the tutorial, browsing the web and seen presentations I get a
> pair of errors, first one trying to use the One Click Experience with
> the beta version and the second, making the first tutorial in the docs,
> that seems, in some, way oriented to people with more experience with
> Smalltalk instead of total newbies like me.
>
> I'm trying Seaside now, which has a more comprehensive documentation,
> but I plan to be part of Aida Community, because I think that the
> Smalltalk web application frameworks (Aida, Seaside, Iliad), need to
> form a strong front to compete with the offers and awareness outside the
> Smalltalk world (web2py, Plone, Ruby on Rails, etc.). I share the idea
> mentioned in the list about Smalltalk frameworks being for people who is
> opinionated about what web development should be (or software
> development in general), and that are willing to learn Smalltalk and
> this is my case. As I said, I will like to help, as a newbie, to show
> what brings me here and what I'm learning, so this could help other
> newbies, and community in making newbies enculturation more appealing
> and fluid.
>
> The first thing is that, being a person who knows about Plone/Zope from
> the end/user point of view, but with a critical perspective of web
> development I want to keep me in a language that was not "web only",
> (like php) and with strong communities in other areas of my interest,
> like scientific computing, and with stronger ubiquity in
> programming/extending a lot of other programs, so python seems a
> language that I want to have in my belt. The thing that I don't like
> about Zope was the complexity and searching for simple and powerful web
> application frameworks made in Python I found web2py which was for long
> time the framework I thought I would use for my first development, even
> considering its similitudes with Smalltalk in the sense of having a
> integrated development environment and the continuity between the
> deployment and the development environments. But it was not. The reason:
> I want to made also a desktop app and web2py was python for the web
> "only", so If I want to make this desktop app I will need still learn
> something like PyQt and dealing with porting/support to different
> environments, as I have witness myself in the case of PyQt for mac, and
> still dealing in the web development with some issues about different
> mental models: objects in python, tables in databases and template
> languages with their mixing/escapes of/to html and javascript. The One
> Click Experience of Pharo/Squeak and the possibility to deal with
> desktop and web developments inside a single environment with high
> portability and just one click away from my intended users and last but
> not least without dealing with license issues of privative software, was
> what finally convinced me to made all my development on OCE/Pharo.
>
> Then became the decision about Seaside/Aida. I don't like the urls on
> Seaside and being a total newbie, having clean REST url in Aida and the
> familiarity with a MVC model in web2py inclined me to Aida at first,
> but, as I said, making the first tries and not finding comprehensive
> documentation made me go to Seaside willing to solve the ugly url's
> which, by the way, is supported, but is just not the default (because of
> the use of continuations and a stateful philosophy). I can understand
> the difference between communities that let the Seaside people to
> construct detailed documentation (the tutorial[1] and the Seaside Book).
> As you can see they're done by people related to academy, teachers
> and/or doctoral students, so this material is part of their teaching
> practice, while Aida is a smaller community with less academical ties.
> But after almost 15 years of development, Aida is needing desperately a
> comprehensive documentation in the form of a book (the docs here and
> there are worth, but not comprehensive). I think that the model Hasso
> Planner Institut at [1] is the model to follow for this first attempt of
> comprehensive documentation directed to newbies, familiar with object
> oriented concepts, but not with a strong background in Smalltalk. I
> understand that this work is under a creative commons non-commercial
> non-derivatives license, but I think that talking with the authors would
> let them to relicense it under a more liberal one (may be creative
> commons non-commercial share alike, or a CC-SA) so this book can be the
> base for the Aida Book in the same way that happened with Squeak by
> Example book as a base for the Pharo by Example book. I also have my
> comments about the ToDo application as a first application in the
> tutorial, but they will be for another mail (this is getting too long
> now ;-) )
>
> [1] http://www.hpi.uni-potsdam.de/hirschfeld/seaside/tutorial
>
> As I said I will be learning Seaside first, using their comprehensive
> documentation, but I think that Smalltalk frameworks need to be in a
> continuous cross-pollination or even integration to offer strong
> competence and appealing for the people outside Smalltalk and I hope
> that this mail could help modestly in that direction.
>
> Cheers,
>
> Offray
> _______________________________________________
> Aida mailing list
> [hidden email]
> http://lists.aidaweb.si/mailman/listinfo/aida
>

> Hi,
>
> El 24/07/11 01:55, Geert Claes escribió:
>> Just out of curiosity, you seem to have tossed up between Seaside and AIDA,
>> what about Iliad?
>
> Documentation on Iliad seems even less comprehensive and addressed
> towards experienced people so I don't even try Illiad. Concepts between
> Aida and Illiad seem pretty similar and I'm curious about why Nicolas
> let their role as a core developer of Aida and went for its own
> framework. ¿Why the ideas of Illiad could no be implemented in Aida?
>
> Cheers,
>
> Offray
> _

> 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.

>  and I'm curious about why Nicolas
> let their role as a core developer of Aida and went for its own
> framework. ¿Why the ideas of Illiad could no be implemented in Aida?
>
> Cheers,
>
> Offray
> _______________________________________________
> Aida mailing list
> [hidden email]
> http://lists.aidaweb.si/mailman/listinfo/aida

>
> 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
> [hidden email]
> http://lists.aidaweb.si/mailman/listinfo/aida