Documentation, how to improve it?

Dear Aiders,

The main remaining problem Aida has is documentation. See Christmas
wishes, see commentaries on mailing lists, docs, docs docs!

So, question is, how to improve Aida docs? How to approach that problem
and resolve it, having in mind that writing docs is not something we
technical people really like? I for instance know its importance but it
is much harder to convince myself to actually start writing it.

One possible path would be:

  1.someone start writing docs, directly on the Aida website,
  2.ask here questions and we will answer them
  3.collect answers on the Aida docs on website.

What do you think, is this a way to go?

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

Maybe it would be a better idea to start by creating short video's?  A bit like the Pharocasts or the video's James does (maybe James can do some AIDA video tutorials?).  Having someone explain things while showing it is a much stronger message than just read it.  Having said that, I do realize that this does not work for all levels of detail but it is an idea to boost AIDA :)

That's a great idea - maybe we should have a YouTube Aida/Web channel?

On Friday 25 Feb 2011 09:57:27 Geert Claes wrote:

>

> Maybe it would be a better idea to start by creating short video's? A bit

> like the Pharocasts or the video's James does (maybe James can do some AIDA

> video tutorials?). Having someone explain things while showing it is a much

> stronger message than just read it. Having said that, I do realize that

> this does not work for all levels of detail but it is an idea to boost AIDA

> :)

>

--

Nicholas Moore

Skype: tsr_nicholas

Check out my Blog

"Still Running - that I may die in good health"

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

On 25. 02. 2011 11:38, Nicholas Moore wrote:

> That's a great idea - maybe we should have a YouTube Aida/Web channel?

Super idea, let we do that! Anyone with a minute of time?

For the video it would be really nice if someone with good English
accent make it. Of course I can't remember anyone with better one than
is yours, Nicholas :)

We can of course help preparing together the scenarios for few such
videos. I'd start with emphasizing the Aida's biggest strength:
seamlessly integrated Ajax support, specially one in Aida 6.2...

FYI, with Friedrich we are working on basic but totally ajaxified CRUD
example, again to show the strengths for most basic but also most
frequent web app patterns.

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

OK - I just tried to create a Youtube account: 'AidaWeb' - but that is not available - if anyone has registered that and could let us know that would be helpful.

In the mean time I have created an account: 'AidaWebSmalltalk'. That can be changed if another name is thought to be more appropriate.

My first thoughts are that we will think of different videos for different audiences. For instance an introductory video could provide an overview and present Aida's great strengths, such as integrated ajax and the power of Smalltalk.

I was also thinking of a video for beginners which simply installed a Smalltalk image and got the example web site running. That opens the way for subsequent videos which begin to customise the web site and gradually introduce more sophisticated topics - such as using ajax and modifying javascript methods. That way new ideas are introduced with a context and a purpose.

In practise, I expect that different people would be thinking about/ developing different aspects of Aida/Web - distributed intelligence (!). :-))

Time permitting I am happy to talk - especially after the kind comments from Janko! I have not made a tutorial video before, so there will be a small learning curve - but then it should be fun.

Maybe this should go into a new thread?

Nicholas

On Friday 25 Feb 2011 11:48:03 Janko Mivšek wrote:

> :)

--

Nicholas Moore

Check out my Blog

"Still Running - that I may die in good health"

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

Nicholas Moore wrote

OK - I just tried to create a Youtube account: 'AidaWeb' - but that is not available - if anyone has registered that and could let us know that would be helpful.

In the mean time I have created an account: 'AidaWebSmalltalk'. That can be changed if another name is thought to be more appropriate.

Not that I do not want to make this about which is the best video hosting site, but I would go for a Vimeo Channel.  I find for example James's Vimeo channel much better than the Youtube one, better quality, nicer UI ... or just do both?

Nicholas Moore wrote

My first thoughts are that we will think of different videos for different audiences. For instance an introductory video could provide an overview and present Aida's great strengths, such as integrated ajax and the power of Smalltalk.

I was also thinking of a video for beginners which simply installed a Smalltalk image and got the example web site running. That opens the way for subsequent videos which begin to customise the web site and gradually introduce more sophisticated topics - such as using ajax and modifying javascript methods. That way new ideas are introduced with a context and a purpose.

Just a thought, AIDA runs on multiple Smalltalk implementations but for the screencasts I would pick one (e.g. PharoAIDA one-click, and publish this exact image for download on the AIDA website) and stick with it throughout the screencasts so people can follow the steps in the tutorials.

Nicholas Moore wrote

In practise, I expect that different people would be thinking about/ developing different aspects of Aida/Web - distributed intelligence (!). :-))

Time permitting I am happy to talk - especially after the kind comments from Janko! I have not made a tutorial video before, so there will be a small learning curve - but then it should be fun.

Maybe this should go into a new thread?

Janko is probably in the best position here to give some advice here on subject for the screencast but starting with where to download and install is a good idea, followed by simple walking through the IDE and showing where the AIDA packages are before showing the sample apps etc

This is good stuff!  Let us know here which video channel you guys have settled on so I can add it to the world.st videos.

Something like this for AIDA: http://vimeo.com/channels/st4u :)

Hi Geert,

On 26. 02. 2011 08:42, Geert Claes wrote:

> Not that I do not want to make this about which is the best video hosting
> site, but I would go for a Vimeo Channel.  I find for example James's Vimeo
> channel much better than the Youtube one, better quality, nicer UI ... or
> just do both?

How credible is Vimeo long-term? What is their business model? YouToube
beeing under Google is pretty sure to survive any crisis, but Vimeo?
While I agree Vimeo is nicer, I also don't like that we loose everything
in case of their bancrot.

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

On 26. 02. 2011 08:42, Geert Claes wrote:

> Just a thought, AIDA runs on multiple Smalltalk implementations but for the
> screencasts I would pick one (e.g. PharoAIDA one-click, and publish this
> exact image for download on the AIDA website) and stick with it throughout
> the screencasts so people can follow the steps in the tutorials.

Agree completely. Let we choose Aida OneClick based on Pharo 1.2 from
our website as a base.

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

On 26. 02. 2011 08:42, Geert Claes wrote:

So, let we start with basic installation of Aida in fresh Pharo
OneClick. Or even just simply how to download and start our preprepared
Aida OneClick and make a short excursion through the demos and even
admin part, which is now nicely ajaxified?

Ok, maybe OneClick download and start, then login, then open an account
for you and put you in Administrators group? Nicelly for one minute
video and you see most of Aida in action :)

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