Search · Index

Documentation Project

Documentation Project

We are trying to develop a consensus in managing the OpenACS documentation. Please see the en:Documentation_Project_Plan and en:Documentation_Project_Discussion for current status.

 The info below is subject to change. See above.

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.

• One can use the follwing script to generate the page objects and load it via xowiki/admin/import into an xowiki instance; this can be improved in many places, but gives you the idea
  
• # by Gustaf Neumann 
• # load doc pages into xowiki   -gustaf neumann
  # for tdom
  lappend auto_path /usr/local/aolserver4/lib
  package require tdom
  package require XOTcl; namespace import ::xotcl::*
  package require xotcl::serializer
  
  set docpath /usr/local/openacs-4/packages/acs-core-docs/www/
  
  namespace eval ::xowiki {
    Class create Page -parameter { {lang en} {description ""} {text ""}
      {nls_language en_US} {mime_type text/html} name title text }
  
    set c 0
    foreach docpage [glob $docpath/*.html] {
      set f [open $docpage r]; set data [read $f]; close $f
      dom parse -html $data doc
      $doc documentElement root
  
      set content ""
      foreach n [$root selectNodes //body/*] { append content [$n asHTML] \n }
   
      set p [Page create page[incr c] -name en:[file tail $docpage] \
             -title [[$root selectNodes //title] asText] \
             -text [list $content text/html]]
      puts [::Serializer deepSerialize $p]
    }
  }

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:

• browse to docbook url (somthing in this tree: http://openacs.org/doc/)
• view page source
• copy the relevant part of source
• paste that source to your favorite text editor (not word processor). I use bbedit, but emacs should work, too
• edit the page source, removing DIV tags and TARGET="_blank" attributes. Look for any immediate way to improve the document, make additional edits, check for spelling etc.
• In a browser that is uncompatible with Xihna, open or create the xowiki page, be sure to make Name starting with "en:" Because Xihna is uncompatible (such as with safari versions < 1.3), the page shows with textarea full of html instead of rendered html and javascript editor.
• paste edited source into the new xowiki page, repeat editing if needed
• click "ok" to post the new page into xowiki. That's it!

Malte here:

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:

• Beginner, Intermediate, Advanced Developers
• Beginner, Intermediate, Advanced System Administrators
• Beginner, Intermediate, Advanced Designers
• End Users
• Subsite Administrators (for clients who want to admin their own subsites)
  
• Potential Clients. This will be a marketing document whether we like it or not.
  

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:

• en:docs-end-user-reqs
• en:docs-admin-reqs
• en:docs-install-reqs
• en:docs-dev-tutorial-reqs
• en:docs-eng-reqs

Step #3. Write new documentation to satisfy requirements for Step #1.

 

A working proposal based on above

While using the requirements of step #2 as the goal, do the following:

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:

• Section 2 DONE
• Section 3 DONE
• Section 4 (IN PROGRESS)
• Section 5 TO DO
• Section 6 Production Environments TO DO (start/stop AOLserver and keepalive are DONE)
• Secton 7 Database Management TO DO
• Section 8 TO DO
• Appendix A TO DO
• Appendix B TO DO (install Tsearch/FTS done)
• Appdenx C DONE

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]

Example documentation outline in wiki

These pages contain links to other pages where items are discussed in context:

Name	for/description
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	administrators
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	developers
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:aolserver	AOLserver
en:aolserver-install	installing AOLserver
en:aolserver-admin	administrating AOLserver
[en:naviserver]	naviserver
[en:naviserver-install]	installing naviserver
en:oracle	Oracle relational database
en:oracle-install	installing Oracle
[en:oracle-admin]	administrating Oracle
en:postgresql	PostgreSQL relational database
en:postgresql-install	installing PostgreSQL
en:postgresql-admin	administrating PostgreSQL
en:os-nix	*nix operating system
en:os-nix-install	installing an OS
en:tcl	tcl language
en:tcl-install	installing tcl
en:openacs-subsystem	OpenACS subsystem (layer)
en:openacs-subsystem-install	install OpenACS

Auxiliary systems

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