Aida comprehensive documentation: a newbie experience

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
13 messages Options
Reply | Threaded
Open this post in threaded view
|

Aida comprehensive documentation: a newbie experience

Offray
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
Reply | Threaded
Open this post in threaded view
|

Re: Aida comprehensive documentation: a newbie experience

Geert Claes
Administrator
Just out of curiosity, you seem to have tossed up between Seaside and AIDA, what about Iliad?
Reply | Threaded
Open this post in threaded view
|

Re: Aida comprehensive documentation: a newbie experience

Janko Mivšek
In reply to this post by Offray
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.

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?

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.

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.

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

Thanks again and keep posting more!

Janko


S, Offray Vladimir Luna Cárdenas piše:

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

--
Janko Mivšek
Aida/Web
Smalltalk Web Application Server
http://www.aidaweb.si
_______________________________________________
Aida mailing list
[hidden email]
http://lists.aidaweb.si/mailman/listinfo/aida
Reply | Threaded
Open this post in threaded view
|

Re: Aida comprehensive documentation: a newbie experience

Offray
In reply to this post by Geert Claes
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
_______________________________________________
Aida mailing list
[hidden email]
http://lists.aidaweb.si/mailman/listinfo/aida
Reply | Threaded
Open this post in threaded view
|

Re: Aida comprehensive documentation: a newbie experience

Offray
Hi,

El 25/07/11 08:45, Offray Vladimir Luna Cárdenas escribió:

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


It was "why Nicolas leave their role..."

Cheers,

Offray
_______________________________________________
Aida mailing list
[hidden email]
http://lists.aidaweb.si/mailman/listinfo/aida
Reply | Threaded
Open this post in threaded view
|

Re: Aida comprehensive documentation: a newbie experience

Offray
In reply to this post by Janko Mivšek

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
Reply | Threaded
Open this post in threaded view
|

Re: Aida comprehensive documentation: a newbie experience

Janko Mivšek
In reply to this post by Offray
S, Offray Vladimir Luna Cárdenas piše:

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

They actually are imeplemented, just look at the current bleeding edge
'e update' in Aida, this one was heavily influenced by #markDirty from
Iliad. And in accordance to the main principle of dialectics: thesis,
antithesis, synthesis, also enhanced into the next level. This is a way
of cooperation, cross-pollination if you like and it is working very
well between Aida and Iliad! I hope once Seasiders will join this party
too :)

Nico otherwise was too inpatient with his bag of ideas and rather to
wait Aida to implement it, it merge best ideas from Aida and Seaside in
Iliad instead. Well, as said we are merging now back :)

Best regards
Janko

--
Janko Mivšek
Aida/Web
Smalltalk Web Application Server
http://www.aidaweb.si
_______________________________________________
Aida mailing list
[hidden email]
http://lists.aidaweb.si/mailman/listinfo/aida
Reply | Threaded
Open this post in threaded view
|

Re: Aida comprehensive documentation: a newbie experience

Nicolas Petton
In reply to this post by Offray
Le lundi 25 juillet 2011 à 08:45 -0500, Offray Vladimir Luna Cárdenas a
écrit :
> 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.

Sorry to hear that. I think Iliad has a simple API. What part of the doc
seemed addressed toward experienced people?
 
>  Concepts between
> Aida and Illiad seem pretty similar

There are some important differences though. Anyway I still follow this
ML closely and we're always in discussion with Janko about new stuff in
Aida/Iliad and ways to implement them.

Cheers,
Nico

>  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

--
Nicolas Petton
http://www.nicolas-petton.fr

_______________________________________________
Aida mailing list
[hidden email]
http://lists.aidaweb.si/mailman/listinfo/aida
Reply | Threaded
Open this post in threaded view
|

Re: Aida comprehensive documentation: a newbie experience

Nicolas Petton
In reply to this post by Janko Mivšek
Le lundi 25 juillet 2011 à 23:06 +0200, Janko Mivšek a écrit :
> Nico otherwise was too inpatient with his bag of ideas
Janko, hehe, I couldn't help but catch this sentence :)

Hmm, was I impatient? I think at some points we just had different ideas
about web frameworks.

Cheers,
Nico

--
Nicolas Petton
http://www.nicolas-petton.fr

_______________________________________________
Aida mailing list
[hidden email]
http://lists.aidaweb.si/mailman/listinfo/aida
Reply | Threaded
Open this post in threaded view
|

Re: Aida comprehensive documentation: a newbie experience

Janko Mivšek
S, Nicolas Petton piše:
> Le lundi 25 juillet 2011 à 23:06 +0200, Janko Mivšek a écrit :

>> Nico otherwise was too inpatient with his bag of ideas

> Janko, hehe, I couldn't help but catch this sentence :)
>
> Hmm, was I impatient? I think at some points we just had different ideas
> about web frameworks.

I'm of course joking a bit, but on the other side some of your ideas is
actually coming in Aida - with a delay! :)

Janko

--
Janko Mivšek
Aida/Web
Smalltalk Web Application Server
http://www.aidaweb.si
_______________________________________________
Aida mailing list
[hidden email]
http://lists.aidaweb.si/mailman/listinfo/aida
Reply | Threaded
Open this post in threaded view
|

Re: Aida comprehensive documentation: a newbie experience

Janko Mivšek
In reply to this post by Offray
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 [hidden email], 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
> [hidden email]
> http://lists.aidaweb.si/mailman/listinfo/aida

--
Janko Mivšek
Aida/Web
Smalltalk Web Application Server
http://www.aidaweb.si
_______________________________________________
Aida mailing list
[hidden email]
http://lists.aidaweb.si/mailman/listinfo/aida
Reply | Threaded
Open this post in threaded view
|

Re: Aida comprehensive documentation: a newbie experience

Offray
Hi,

El 25/07/11 17:09, Janko Mivšek escribió:
> Hi Offray,
>
> Good anecdote about "she is my girlfriend, but she don't know", I need
> to remember that one, hehe.

Yep :) I made a mistake is "she is my girlfriend, but she doesn't know".

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

I have seen that. Thanks.

> 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 [hidden email], maybe we can ask him too?

I think that Guiseppe has done a good work but we don't ask him about
translation, because the original work is covered by a Creative Commons
By License, but he could help with Spanish documentation and Yes I can
do the updated translation as far as I get understood and done what the
original says, in my own machine (I don't want to translate what I don't
understand or can get working in my environment). So, until now I can't
go further with:

book := ADemoAddressBook new.
book
    addAddress:
      (ADemoAddress newName: 'Sebastjan' surname: 'Dormir' phone:
'01/514 33 66' email: '[hidden email]');
    addAddress:
      (ADemoAddress newName: 'John' surname: 'Newton' phone: '05/555 77
66' email: '[hidden email]');
    addAddress:
      (ADemoAddress newName: 'Elizabeth' surname: 'Schneider' phone:
'03/561 23 12' email: '[hidden email]').

and I get the error:

ADemoAddress(Object)>>doesNotUnderstand:firstName

and I don't know who to debug this error or why is present if I have
done what supposedly is right. In contrast, for the moment, the Seaside
tutorial advance seamlessly and I have my first url working as expected.
So, I'm suspicious about if all the code that appears in the Address
Book example is all what is supposed to be filled or if sentences like:

"create accessors and mutators for all instvars in class ADemoAddress"

suppose to fill in something more in the browser that a knowledgeable
people should know but the newbie don't (the first sentence like that
created 3 instance methods for ADemoAddressBook).

I really want to help with Aida and other Smalltalk frameworks but I
feel that I need to get something running smoothly before trying further
attempts because I don't want to be going from docs to community, to the
image, to frustration, to docs, to... in short cycles again and again.
Having comprehensive documentation will enlarge that cycles and reduce
the necessity for continuous support. So my proposal before any
translation is this:

Could you try to change the address book tutorial in such way that all
the code that is needed to be typed is explicitly stated and some
glossary for terms like "accesors", "mutators", "insvar" could be
defined previously or avoided as in the Seaside Tutorials? If I can go
through this tutorial smoothly I can help another newbies to made the
same with the Spanish translation. By the way, for translations, the
suggested infrastructure for me should be:

https://www.transifex.net/


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

I agree. We need to get first this address book tutorial working for
newbies and then go for more complex apps like the todo or some other
ideas, to start with this comprehensive documentation effort.

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

Lets continue the started discussion about the ToDo example in private,
with the first reported inconsistencies. I don't know the space of
JQuery, but having a proper examples in the demo app about the use of
Javascript for interactive web pages, as the ones that are in Seaside
should be part of the default experience (I don't know if using just
Ajax of something else).


> And of course, more feedback, more feedback :)
>
> Best regards
> Janko
>

Hope this helps.

Best regards,

Offray
_______________________________________________
Aida mailing list
[hidden email]
http://lists.aidaweb.si/mailman/listinfo/aida
Reply | Threaded
Open this post in threaded view
|

Re: Aida comprehensive documentation: a newbie experience

Offray
Hi again,

I just want to say to you that my suspicious was correct, when I said:


El 26/07/11 09:46, Offray Vladimir Luna Cárdenas escribió:
[...]
> So, I'm suspicious about if all the code that appears in the Address
> Book example is all what is supposed to be filled or if sentences like:
>
> "create accessors and mutators for all instvars in class ADemoAddress"
>
> suppose to fill in something more in the browser that a knowledgeable
> people should know but the newbie don't (the first sentence like that
> created 3 instance methods for ADemoAddressBook).

[...]

So, effectively create accessors and mutators need a more detailed
explanation for me. I get the clue following the Seaside Tutorial, when
it says:

"
it is highly recommended that you perform automatic creation of instance
variable accessors. One possible way to do this in Squeak is to use the
context menu on a class among the entry more.... There, you can find
create inst var accessors. Select this command to have all accessors
created. In different browsers or environments, this feature may be
accessed differently, so consult your system documentation in case you
are not using Squeak and its standard browser. When all else fails, you
will have to use hand-written accessor methods.
"

Notice that this kind of constant comparison with Seaside is just for
the sake of saying how can the documentation of Aida be written so a
newbie can get more with this framework easily.

Now I have my first ordered collection filled in the address book
example and I'm ready to go for my first working url, but that will need
to wait until tonight.

Cheers,

Offray
_______________________________________________
Aida mailing list
[hidden email]
http://lists.aidaweb.si/mailman/listinfo/aida