This page is to help Rob and Ryan organize the documentation.
This page is temporary and will be used simply as a simple reference page on what we are attempting to do and on our progress.
STAGE A: CONVERT DOCUMENTATION TO XOWIKI
(note: all api docs remain the same)
Step #1. Catalog the current documentation.
Hi, Torben, here. I am porting the below docbook pages to xowiki manually, because it allows me to look at each part in details and separate to subsystem/object context. Here is the process:
Instead of doing it manually (though this does have some merit), I would go and modify the script Gustaf provided to import the whole documentation in one go into a new XoWIKI instance with the structure (page_order) that has been added in XoWIKI 0.42 taken from the chapters of the documentation so that we do have an exact mirror of the documentation as it stands now.
Once this is achieved we could go on and assign categories to the documentation, allowing for an alternative view on the documents (so you could say "instead of showing the whole documentation only show the documents for a specific category"). Probably this needs some more detailed discussion with Gustaf finding out how this could be achieved in XoWIKI and what would make most sense. Ideally we could provide a different structure based on the target group (e.g. category) but this is probably shooting too far. Getting categorization and page ordering in a decent shape should provide us a lot of possibilities. This would be incorporated in Step #2 below.
Step #2. Slice up the conversion process into stages / sections
considering subdividing by subsystems and how they are used (context). Why?
"..the human mind can only deal with a relatively small number of independent pieces of data at one time, but if data are chunked together in appropriate ways, the mind can perform higher order abstractions, and these in turn can be chunked together, with successive abstractions, until an entire complex situation is encompassed. The systems approach addresses this property of the human mind by providing strategies for the data gathering, chunking, and abstracting process." George G. Lendaris, On Systemness and the Problem Solver: Tutorial comments 1983.
The xowiki docs can use a systems strategy of multiple perspectives to help identify subsystems and how OpenACS works. Each xowiki page discusses a single topic. These topics are then pieced together by any number of other xowiki pages to present an ordered presentation of the topics with a common thread/topic connecting them. For example, en:openacs-system-install is a page that links together the topics of installing the component software of Openacs. Similarly, each component software, such as en:aolserver, has its own view of some overlapping topics. Xowiki documents organized by subsystems (and how they are used) are easy to update and maintain since there is only one place to put relevant information for a particular topic. Pages are not encumbered by a maze of categories that tend to only address one or a few perspectives, since pages link to related pages, and a page that addresses each perspective can link to overlapping topics.
The hope is that xowiki will be able to export a page and all the pages that link to it, to any number of degrees of separation, to form one document --similar to how wget can get a website N directories deep. That way, innumerable documents, each with a valid perspective, can be built for a specific purpose.
Step #3: Create and vet categories based on step #1 and #2.
Step #4. Begin conversion process and track progress.
STAGE B: BEGIN TARGETING DOCUMENTATION AT VARIOUS USER GROUPS
Step #1. Outline documentation needs for the following Actors/Stakeholders:
A proposal to use community generated documentation requirements to shape the outline.
Step #2. Organize existing documentation for user groups.
Here are documentation requirements for:
Step #3. Write new documentation to satisfy requirements for Step #1.
1a. Move all but maybe the first and last 2 items from http://openacs.org/doc/dev-guide.html to http://openacs.org/doc/kernel/dev-guide.html and refer to them in context of the kernel package (or whatever package their code is in). That helps developers see appropriate context. (This will likely require a board discussion and TIP)
1b. Allow document writers to find the local package_id so a link can be supplied from the local documentation to current, up-to-date API and SQL docs, like: http://openacs.org/api-doc/package-view?version_id=358136 use links like this: /api-doc/index?about_package_key=acs-datetime The feature has been added to cvs head (OpenACS 5.3.x) so will be released soon.[DONE]
2. Move Administrator's Guide to the xowiki. (in progress) Progress report:
3. Incorporate the work already done in the first wiki. Note that some of this will already exist in xowiki from previous importing of docs etc. [TO DO]
These pages contain links to other pages where items are discussed in context:
|en:docs-end-user||documentation for everyone|
|en:openacs-system||end-user about OpenACS system, ties together much of the stuff below.|
|en:docs-end-user-reqs||end-user doc requirements and checklist|
|en:docs-install||installing OpenACS prerequisits|
|en:openacs-system-install||installing OpenACS overview|
|en:openacs-system-install-redhat||installing OpenACS on Redhat|
|en:docs-install-reqs||installation- docs requirements and checklist|
|en:docs-admin-reqs||administration - doc requriments and checklist|
|en:docs-dev-tutorial||tutorials for developers|
|en:docs-dev-tutorial-reqs||developer tutorials - requirements and checklist|
|en:docs-eng-reqs||developing - requirements and checklist|
These pages describe the various OpenACS subsystems, and link to external documents where possible and appropriate. Note that an "OpenACS system" en:openacs-system page that outlines the system and ties these together would be part of the end-user docs.
|Name||subsystem of OpenACS|
|en:oracle||Oracle relational database|
|en:postgresql||PostgreSQL relational database|
|en:os-nix||*nix operating system|
|en:os-nix-install||installing an OS|
|en:openacs-subsystem||OpenACS subsystem (layer)|
|en:ide-emacs||gnu emacs as IDE|
|[en:ide-emacs-nxml]||gnu emacs nXML Mode|
|[en:ide-emacs-psgml]||gnu emacs PSGML Mode|
|en:ide-vi||vi/vim as IDE|