Forum OpenACS Q&A: Re: New OpenACS Tutorial

10: Re: New OpenACS Tutorial (response to 1)
Posted by Dave Bauer on
This looks really great, I see you put quite a bit of effort into it. I did some some funky formatting in the PDF on OS X. I'll try to test on some other PDF viewers to compare.

I think it might be a gentler introduction to use the subsite "Applications" page to setup the TODO notes package intead of the site map and introduce site-map later if necessary for more advanced features.

I see when you add the todo items you use acs_object_id_seq.nextval instead of nextval('t_acs_object_id_seq'); This would be confusing to those not accoustomed to the sequence view hack used to make it similar to Oracle syntax. It would be good to explain why you do that.

In defining the Tcl API, the procedures do not have a documentation block. I think it is best practice to use the documentation block along with @param @return tags.

These are all things that could be addressed when the source of the tutorial becomes available. I'll try to review the tutorial some more. We want to make sure
1) The tutorial matches our engineering standards and
2) The documentation for our engineering standards are up to date.

Thanks again for doing this work, I hope we can make improvements to this tutorial and keep it up to date with the current best development practices.

Posted by Rocael Hernández Rizzardini on
I agree, will be simpler to use subsite applications, although the tutorial also goes directly to what you have to do and doesn't stop on the other things you might be able to do at site-map.

Yes, we need to correct the proc declaration to use auto-documentation, and do a very brief note about documentation features.
Also a note on the sequence hack can be made, I really do not expect newbies to focus much on that, maybe we can add a footnote.

Not sure whether we'll keep the sources in Word as they are now or not. So far they are good for producing the pdf, we still need to figure out that. Formatting is important for the tutorial.