I would like to propose a more complete framework for documentation since having excellent explanations for the system will do wonders for its adoption and use (among current openacs hackers and others). I will post a more complete idea of what I'm talking about (after I speak with Pat Colgan, my colleague at Musea and a guy with really good ideas) but here are some initial ideas:
* The first and most important (i think) aspect of a doc is the Executive Summary, which the Big Picture tries to fulfill but generally screws up. This should explain the functional and technical aspects of a module so that an OpenACS hacker, a newbie hacker, and a totally non-tech person can understand what is going on. This is the most difficult part of documentation, but once you get this part right everything else is easy.
* There should be a a doc module that uses the DB. This is important so that elements of a doc can be posted in various areas, i.e. Exec Summ can be posted on a list of summaries for each module, the data module can be listed in another area with other data models, etc.
* There should be an element of a Wiki there so that people can collaboratively work on these docs. For instance, some people may not be very good at writing Executive Summaries so that everyone might understand. It would be nice if other members of the community can help make these docs more accessible. An "edit this page" element would be great for this.
* That we or a subset (Roberto and Don come immediately to mind since they have experience) establish the *essential* parts of documentation. So that a person writing documentation, for instance, knows that they have to include an Executive Summary, a data model and installation instructions at the very least.
These are my initial suggestions. I'm sure others have other points to fill out the proposal more completely.
talli
