Forum OpenACS Q&A: What documentation does OpenACS need to train a new programmer?

1: What documentation does OpenACS need to train a new programmer?

Posted by Dave Bauer on 09/14/04 08:07 PM

This forum thread is inspired by this comment on the #openacs IRC channel:

lluad: The main reason I'm concerned about the lack of docs is that I can't commit my company to using OACS, as I don't
believe I could train a new hire to be able to work on it.

So, what documentation would be needed to train someone to work with OpenACS. I guess there are a couple of types of uses

1) editing ADP templates
2) customizing an existing package
3) building a new package

What existing documentation is there, and how can it be organized to train someone?

Please discuss!

2: Re: What documentation does OpenACS need to train a new programmer? (response to 1)

Posted by Dave Bauer on 09/14/04 08:12 PM

A big part is the package developer's guide
https://openacs.org/doc/current/tutorial.html.

There is also the huge amount of information here https://openacs.org/doc/current/acs-package-dev.html but there isn't any doc that ties everything together explaining how you can actually accomplish something with it.

3: Re: What documentation does OpenACS need to train a new programmer? (response to 1)

Posted by Dave Bauer on 09/14/04 08:15 PM

More ideas,

We need a tutorial that includes using the CR and the new CR Tcl API.

A definitive, accurate guide on using permissions in a real application.

A guide to using optional services, search, comments, attachments, notifications, workflow.

4: Re: What documentation does OpenACS need to train a new programmer? (response to 1)

Posted by Nima Mazloumi on 09/14/04 10:17 PM

Dave, I discussed that already with Jade and Malte. As soon as dotlrn 2.1 is out and we upgraded successfully I will first bring all little how to stuff on the web to the OpenACS documentation incl. Jade's articles. Then together with Malte we will write a detailed documentation. So what we need are other community members who can contribute on more specialized items like permissions, object model, CR tcl api, scheduled procs, call backs, dotlrn integration ...

5: Re: What documentation does OpenACS need to train a new programmer? (response to 1)

Posted by Nima Mazloumi on 09/14/04 10:20 PM

The course editor we are working on here at the university of mannheim could also be helpful. We could create whole course repository on all the different subjects you listed above.

The editor second version will generate docbook and scorm/ims compliant courses that we could offer on openacs.org using ernie's lors package.

So what we need is an upgrade and redesign of the current openacs.org site.

What do you think?

6: Re: What documentation does OpenACS need to train a new programmer? (response to 1)

Posted by Rocael Hernández Rizzardini on 09/15/04 01:43 AM

Its hard to think about what might be a good start for a new developer, of course, you expect them to be able to understand sql querys, scripting programming, how a http communications work, how webserver works in general, etc. (I have found really difficult for new developers to work on openacs when they dont have the concepts clear), but anyway, its not clear for me what could be a good start for them (recent openacs developers might give us their perspective here).

Anyway, we plan (Galileo), to put together an openacs course being it SCORM compliant, which should be helpful for anyone learning by themselves online. Then, we call as well for comments about making the start easy for new developers in oacs.

7: Re: What documentation does OpenACS need to train a new programmer? (response to 1)

Posted by Chris Davies on 09/15/04 02:08 AM

How about a sample package, well documented, that illustrates the best practices? I would say that it should include perhaps file storage, CR, Translations, ad_form/templating and more. Or, perhaps an existing module cleaned up to use all of the facilities correctly.

Every time I write a package and people review it, they say -- why didn't you use this part of OpenACS? How come you didn't do that?

Since most of the code I've written is based on other code in OpenACS and documentation I've read -- using existing packages as examples has sometimes led me in the wrong direction.

I'm sure this only means that many of the packages that have been written don't really have a complete grasp of all of the facilities within OpenACS, or that facilities in OpenACS have been written based on ideas or requirements from packages that are authored.

Either way, both of my employees are very intimidated at writing code for OpenACS and even though I've spent a year with it, I am able to write packages, but I wouldn't ever be able to claim that they were written properly for the OpenACS infrastructure. However, as I learn more, they are getting closer to what I would consider using more of OpenACS's power.

8: Re: What documentation does OpenACS need to train a new programmer? (response to 1)

Posted by Frank Bergmann on 09/15/04 03:01 PM

Hi,

there is some (older) material out on http://www.fraber.de/university/bootcamp/. In particular, there is a "Short References" PPT/PDF with a single slide per tool: Emacs, Unix, TCL, HTML, ... for absolute beginners.

We had some good success teaching "black screens" to MBAs at Competitiveness.com using this material. Maybe it would also work for these quiche eating, M$-spoiled kiddies that are around these days ... 😊

Bests,
Frank

9: Re: What documentation does OpenACS need to train a new programmer? (response to 1)

Posted by Dave Bauer on 09/15/04 03:27 PM

Chris,

You are absolutely right. I am working on a simple wiki package using the new CR Tcl API and I will try to document the design process of that as an example.

Nima,

Thanks for that update. What I want to do with this thread is prioritize a list of docs or an outline of what docs we need and get someone working on them. I think your idea is great but maybe a little to big to manage. Let's break it down into smaller tasks.

10: Re: What documentation does OpenACS need to train a new programmer? (response to 1)

Posted by Jonathan Ellis on 09/15/04 07:56 PM

Because the OACS api is getting so huge I'd like to see a simple page with "Here's what you need to know about the guts of OACS." Then links to request processor, templating, package management, etc. Then besides the existing whitepapers, which are mostly good, I'd like to see "Here are the most common API functions you will be calling and examples of use."

11: Re: What documentation does OpenACS need to train a new programmer? (response to 1)

Posted by Windell Dubois on 09/22/04 03:45 PM

I dont know if the Notes package is still available in the most recent versions of OACS. In my opinion, the Notes package is pretty simple in itself, and could prove to be an easy way for new developers to check out the functionality in OACS. I dont think its that well documented, though.

12: Re: What documentation does OpenACS need to train a new programmer? (response to 1)

Posted by Alex Sokoloff on 09/24/04 03:41 AM

A few thoughts from my expererience training three developers on OpenACS:

The old (pre-4.0) OpenACS/ACS classic was relatively simple IMO, and it was easier to build from first getting the webserver to return a page to using the various ACS packages and utilities. With 4.0 and greater, you encounter a lot of complexity from the get-go if you try to actually work with packages. For a sort of quick-start, I wrote some (very simple) documentation and exercises that took the group through retrieving "hello world" from the database and returning it to the browser, using only the db_ api - just to give the developers a quick look at the basics before before plunging into concepts like templates, ad_form, objects and so on. It seemed to help get things rolling.

Also, if you yourself approached OpenACS with some background web applications and UNIX, don't discount the additional things someone with a different background has to contend with. As I recall, OpenACS had a steepish learning curve for developers used to delphi/MS access.

13: Re: What documentation does OpenACS need to train a new programmer? (response to 1)

Posted by Rafael Calvo on 10/26/04 07:17 AM

Hi
A bit about our own experience....
I am about to finish the second run of a "web application framework" course at University of Sydney. This time we had 40 students, last year about 20.

These 4th year students learn a bit about a number of frameworks: WebObjects, Tibco, Interwoven, BEA and of course OpenACS.
In the lectures we had demos of all those products and a discussion on what they are good for, advantages and disadvanatages. We also had a few lectures on design patterns and frameworks as methodologies to improve software/design reuse.
In the labs they learn how to write a simple openacs application and a portlet.

During the whole 13 weeks of the semester we had about about
20hrs of labs dedicated to .LRN and 6hrs of lectures.
Althought we should have had 2hrs more on Tcl and postgresql
3/4 of the students finished some interesting applications.

Later in the year I hope to be able to write a description that includes more on the students' feedback. My feeling is that it takes them 30hours of "assisted" effort (maybe 40) before they can get to a point where they have a basic idea of the framework/APIs and can start doing something useful.

Are there other organizations who would be interested in openACS training? Would these organizations be interested in a 'OpenACS/.LRN certification'?

cheers

Rafael

14: Re: What documentation does OpenACS need to train a new programmer? (response to 13)

Posted by Rocael Hernández Rizzardini on 10/27/04 06:16 PM

Hello Rafael,
this info is really interesting, we did also training to students at Galileo, but the labs should be improved to make them to have a better impact. Do you have the material available?

We are planning to make a simple course about .LRN development, as part of .LRN Sustainability, we need more trained developers and a "clear" road on how to become a .LRN developer (oacs developer), but right now, for most of the people, the learning curve seems still high.

If you like we can collaborate on putting something together online.

The certification in oacs/.lrn has been in my mind for a while, and I think while the .LRN adoption starts to grow (more now that the consortium is doing marketing of .LRN) we will see a natural need for certifications, but that will come later, now probably a "clear" road to become .LRN developer is more important.

15: Re: What documentation does OpenACS need to train a new programmer? (response to 1)

Posted by Nagita Karunaratne on 11/02/04 09:55 PM

As a relative novice to OACS, my opinions is that a high level overview of the entire architecture may reduce that feeling of being overwhelmed. Something similar to this created for PHP:

http://www.tonymarston.net/php-mysql/infrastructure.html

A wiki-type one-page document.

16: Re: What documentation does OpenACS need to train a new programmer? (response to 1)

Posted by Walter McGinnis on 11/05/04 08:41 PM

I'm collecting and reworking documents for some training for a new employee at pps.org. I'm looking for a copy of the old "Datamodel and Query Porting Guidelines" as a kind of cheat sheet about sql differences between Oracle and PG. It used to be at https://openacs.org/new-file-storage/one-file?file_id=120 or possibly http://sdm.openacs.org/new-file-storage/one-file?file_id=120. I've done some searching on web.archive.org and haven't found a copy and the data hasn't been migrated to the new site yet.

Does anyone have a copy of this document that I can take a look at?

Thanks,