Forum OpenACS Q&A: Documentation cleanup suggestion.

Collapse
Posted by Dave Bauer on
Should we remove the "requirements" docs from the documentation? They are mostly out of date. Where there is useful information, it can be rolled into the "Design" documentation.

It will greatly reduce the amount to be maintained.

Collapse
Posted by Peter Marklund on
I wouldn't necessarily remove those docs until we have some replacement. It would be nice if we had indications saying how up-to-date (or out-of-date) documents are though.
Collapse
Posted by Joel Aufrecht on
Could people who are more familiar with the internals indicate which sections in the chapters: are current, and which are outdated?
Collapse
Posted by Peter Marklund on
Some quick feedback. It seems to me most of the documents are quite high quality and actually mostly still accurate since the basics haven't really changed. However, the APM doc in the packages guide (developers guide)

http://aufrecht.org/doc/packages.html

has a couple of small inaccuracies that I am to blame for. File listings in info files are not used anymore. Also, there are new file types for Tcl tests. The doc should make mention of APM callbacks.

It might make sense to weed out all references to ArsDigita (not least the email addresses!). I mean it does feel weird when the doc says that "we at ArsDigita" currently do things this or that way.

Collapse
Posted by Dave Bauer on
Right, I basically want to simplify the docs and roll useful information into one doc. Possibly with a requirements section if people think that sort of thing is necessary. Most new docs end up being written after the code, so requirements aren't really necessary.
Collapse
Posted by Dave Bauer on
The parts referring to the datamodel for permissions need to be changed at least.
Collapse
Posted by Joel Aufrecht on
Oh yeah, and plans and status for documentation are online here.
Collapse
Posted by Peter Marklund on
Joel,
one thing that came to my mind now is that if I was new to OpenACS I would probably be a little intimidated by the sheer size of documentation - we have quite a few lengthy documents and they are not exactly light reading. I would ask myself if I have to read all of them, and if so in which order? Can I get away with reading a subset, in that case which? I don't necessarily have the answers to these questions but I think some kind of documentation guidance would be really cool.
Collapse
Posted by Torben Brosten on
I think this developer info should be integrated into  the docs, if it isn't already:

http://www.infiniteinfo.com/openacs/things2remember.html

This info could help on updating the freebsd docs  (and perhaps integrating them into the linux docs):

https://openacs.org/forums/message-view?message_id=51195

https://openacs.org/forums/message-view?message_id=51126

Also, I  think it's time the doc-associated forums are created as discussed in:

https://openacs.org/forums/message-view?message_id=44661

Collapse
Posted by Jun Yamog on
Hi,

If anyone wants to maintain the Things 2 Remember please email me.  I will however start again its maintenance after a few months when my help comes aboard and I start doing OpenACS related stuff again.  But if someone would like to add, correct, etc. please feel free to do so.  Since I am not with Infiniteinfo anymore.  Can I upload this doc to the file storage?

Collapse
Posted by Gabriel Ricard on
Peter,

As a newcomer to OpenACS, I have to say that I feel exactly the opposite way of your assumption. I want MORE documentation! hehe. I found the existing docs to be a good overhead view of the system, and there is a vast amount of older documentation out there (old ACS Journal articles, and Phil G's books), but that documentation doesn't seem to be relevent to the current state of OpenACS. It helped me to get a good bird's eye view of how it all works, but I want more specifics and cookbook / howto type docs.

Joel's recent developer doc on creating packages was very nice.

As an example of good documentation, I really have to say that PHP and MySQL's websites have very nice documentation with user feedback that often includes more valuable content than the original documentation. In general they both have an organized reference manual and each page has loads of user feedback with examples, gotchas, work-arounds, etc. Can something like that be created for OpenACS?

If I knew more about OpenACS then I'd step up to the plate and create that.

Collapse
Posted by Joel Aufrecht on
  • The tutorial has been updated again, to accomodate everybody's fixes and suggestions. I've also tried to link to detailed material wherever possible. So I'm asking for feedback on the revised tutorial, especially: places where I should add more links.
  • What topics are missing from the advanced section? My intent is that every major feature of OpenACS package development be introduced as a mini-how-to topic. Each of these should be independent of the others, so you can add any single feature to the basic tutorial package in one step.
  • What do we have to do when 4.6.2 ships to get those "View Comments at openacs.org" links at the bottom of every page to work? Is there some way we can alter the template so that, whenever you view a page on your local machine, it reaches out to openacs.org and shows all relevant comments?
Collapse
Posted by Peter Marklund on
Joel,
I like your documentation a lot! Great work! I'll print the docs and get back to you with more detailed feedback.

Ability to comment on the docs is quite important. I don't know how people currently comment static pages. Is there such a solution in OpenACS already? I notice that there is a page package and a static-pages package. Of those the latter seems more sophisticated. Which one should we use? Fetching the comments from openacs.org to a local server wouldn't be difficult once we have commenting set up at openacs.org and every page is identified by a uri.

A few things I think should be in your tutorial are:

1) A few recommended example packages for people to look at. I am thinking the logger package I am developing now might become such a package as it is a relatively small and simple package and hopefully we can make it reflect best practices. It doesn't use CR though.

From point 1) developers can see much of the following:

2) How to group Tcl procs in namespaces.
3) How to make package instances deletable via the site-map and uninstallable using the APM UI by utilizing the before-uninstantiate APM callback.
4) That -procs.tcl files should *only* contain ad_proc statements.
5) That server startup tcl code (scheduling of procs, filters, nsv variables) should live in -init.tcl files in the same tcl directory.
6) That create and drop scripts must follow a naming convention and should source separate table and package scripts.
7) That Tcl API test cases should live in a file named tcl/test/package-key-test-init.tcl and that test support procs can live in -procs.tcl files in that directory.
8) That to use such tests acs-automated-testing must be installed and mounted.
9) That each table in the datamodel should have a comment
10) That each ad_proc should have well written @param and @return tags (i.e. the contact of the proc should be explicit)

Collapse
Posted by Ola Hansson on
Joel, here's more feedback on what you already have in there.

In figure 8.4, the statement;

select define_function_args(samplenote__new,'note_id,title,creation_date,creation_user,creation_ip,context_id');

should read:

select define_function_args(samplenote__new,'note_id,object_type;samplenote,title,creation_date,creation_user,creation_ip,context_id');

(note the added "object_type;samplenote")

This parameter should only be in the "*__new" functions. I haven't studied the code closely and recently enough to be able to explain why it is needed, but I do know from own experience that this is the case.

ad_table:

I found an undocumented feature by looking through the code that may be worth mentioning. $orderby can be made to sort descending by default as opposed to ascending by suffixing the key with a "*" .... So if one says "{orderby:optional {title*}}" the titles (say) will be sorted in the reverse order compared to your example.

Regarding the add/edit page:

The "new_data" block of ad_form doesn't look quite right; either use the "samplenote::new" wrapper _or_ the db_dml statement, but not both at the same time 😊. (Don't forget to include an example derrived from ,e.g., "forum::new" if you follow the wrapper path.)

Collapse
Posted by Jade Rubick on
Hi Joel,

Here is some more documentation feedback.

I found the section with Ola's suggestion a little confusing.

What does samplenote::new mean? It's not really explained anywhere, or linked in anywhere.

I'm fairly familiar with ACS, and have used OpenACS a little, and I found that section totally mysterious. Where does that definition come from? Is it a namespaces thing? I'm not really up on namespaces.

Anyway, I imagine some more explanation might be in order there. I'd offer concrete wording suggestions, but I don't understand it yet. 😊

Collapse
Posted by Jade Rubick on
Hi Joel,

When you get around to it, here is another suggestion:

The samplenote add-edit page looks like this:

<?xml version="1.0"?>
<queryset>
  <fullquery name="do_insert">
    <querytext>
        select samplenote__new(null,:title, :body,null,:user_id,null,null)
    </querytext>
  </fullquery>
  <fullquery name="do_update">
    <querytext>
      update samplenote
          set title = :title,
              body = :body
        where note_id = :note_id
    </querytext>
  </fullquery>
  <fullquery name="note_query">
    <querytext>
      select title,
            body
        from samplenote
      where note_id = :note_id
    </querytext>
  </fullquery>
</queryset>

That first null should actually be the key that is passed in, I think it should be :note_id. You can see this thread for more details of how I came to discover this: https://openacs.org/forums/message-view?message_id=91910