- http://openacs.org/projects/openacs/doc-project/ <-- original documentation project page

Documentation Project now at: http://openacs.org/xowiki/pages/en/Documentation_Project

OpenACS Documentation by context: http://openacs.org/storage/view/miscellaneous/system-versus-roles.html

Notes:

Current documentation is okay, but a lot more needs to be done. I have posted a message to the forums to start looking for ideas on how to get better documentation together as that clearly is the key to solving the "barrier to entry" problem for oacs.

This page will be used to document and organize the push for furthering the documentation of oacs.

Preliminary points from discussions on the topic:

oacs documenations

- two problems so far

     - no organzation
     - no volunteers

- there is a huge AMOUNT of documentation but not the right documentation apparently

- some people get frustrated when they know what to do, but don't know where to start looking for stuff.

- http://openacs.org/doc/current/docbook-primer.html

- some people just search the API-DOC, or poke around and can guess where to look

- casual users will probalby get frustrated and move on to Rails before reading all the core stuff

- maybe a list of 20 questions that narrow down where to look might be useful

- so what do we need for documentation. one problem, openacs is HUGE?!

- a more detailed tutorial style doc would probably be helpful.

- maybe organize it into a map of subsystems

- someone recently trained someone to use OpenACS and the dev said if he wasn't paid to go through the installation process, he would have given up

- take existing packages and hook them togteher to make something new

- you need a group of two people. p1) last feature I added was to package <acs-ZZZ>. I will spend 2 days writing the docs for <acs-ZZZ>. p2) I will take everything <acs-ZZZ> wrote and rewrite it in english and put up examples, making sure p1) isn't talking out of his ass.

    - contacting developers to get them on board is bordering on impossible

    -i've worked as a software engineer.  (p2)'s have a hard time as is, and that's when they can come to s dev's cube 4 times a day to remind them.

    - you have no leverage to get dev's to write docs until they , on their own , realize that it's easier to write docs than support the system without them.

    - if you implement feature X and then spend the next 2 months voiding bugs because people don't use it correctly, you learn to write docs.

    - but if the documentation isn't done you get a: your observation, and b: this framework ain't going no where

    - everyone might as well just drop it and do rails or something else

- how many procs are there in the content repository interface?

     - VAR/LIB/AOLSERVER/OPENACS-5-2/PACKAGES/ACS-CONTENT-REPOSITORY/TCL$ grep 'ad_proc' * | wc -l
     -  how long would it take to go through those and mark which ones are private and which are public?
     - 1 day

- api's are better documented in 5.2

- content repository and templating for the most part seem to need documentation the most

- but the api-doc doesn't tell you enough, just how to call a cetrain procedure, not when you should call it.