Forum OpenACS Q&A: Re: New OpenACS Tutorial
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.
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.