New Documentation Process

New Documentation Process

Official documentation will go into openacs.org/test-doc (to be renamed) generate from there the html pages for documentation, therefore the first result is to update the documentation to reflect current tools, version, correct commands, all done within that wiki instance

The process for generating technical documentation is:

1. Update that documentation wiki instance named doc-head
   
2. Once the documentation is ready, freeze it doing a export/import process from /doc/head to a new instance (i.e. /doc/5-5-0)
   
• No write permissions for the public will be granted to this frozen instances
• Use an alternate template to distinguish between /doc/head and the frozen ones
  
3. Generate the static html documentation based on the wiki-frozen instance (/doc/5-5-0) 
• Using as template_file the view-oacs-docs
• Available here: http://alice.wu-wien.ac.at:8000/xowiki/listing?m=list
• Have to be placed on www dir of xowiki package
• Also the parameter top_includelet have to be in blank for the wiki-frozen instance
• Example on how the doc will be available in the wiki-frozen instance: http://alice.wu-wien.ac.at:8000/test-doc/for-everyone
  
• Options for the static content:
  
• One large HTML file and/or (book-print prototype)
  
• One HTML file per chapter and/or (tutorial-advance prototype)
  
• Same granularity as in /doc/head
• Get the documentation using wget
• This wget command should get you the html files for the documentation:
  
• wget -kpr -R book <root of the documentation's xowiki instance>
• The html files will not have an extension, this may cause them to not be interpreted as html and returned as plain text on some web servers, to be safe, rename the files to have an extension. Run the following script on the directory containing the static html files.
• #!/bin/bash
  
  FILENAMES=`ls . | grep -v "html" | grep -v ".sh"`
  
  for f in $FILENAMES; do
      if [ ! -d "$f" ] ; then
          FILE_NAME=`echo $f | awk -F ? '{print $1}'`
          FILE_PARAMS=`echo $f | awk -F ? '{print $2}'`
          if [ -z "$FILE_PARAMS" ]; then
              NEW_FILE_NAME="${f}.html"
          else
              NEW_FILE_NAME="${FILE_NAME}.html?${FILE_PARAMS}"
          fi
  
          if [ ! -f "$NEW_FILE_NAME" ]; then
              mv $f $NEW_FILE_NAME
          fi
      fi
  done
  
  
  
4. Commit into the CVS, branch and tag appropriately following the branch/tag conventions for the specific release.
   
5. Add a link of this new /doc/5-5-0 into online documentation index openacs.org/doc and a map it in the site map to /doc/current
   

To-Do

• Still missing a way to transform to independent html files with index / navigation within it (right now only produces a one big html). (done by Gustaf)
  
• New /doc has to have a link to the various online (xowiki) frozen versions of the documentation.
  
• Document the document formatting/markup rules in the wiki instance and the static documentation. 
• Probably there is already formats for technical documentation available, produced, or at least some guidelines.
  
• Openacs.org/doc will be replaced with the wiki-documentation (/test-doc instance renamed to /doc/head)
  
• Provide an index to link to all frozen documentation releases.
• Current /doc can be renamed to /doc-5-1
  
• Assign someone to udpate the documentation, follow the process and release documentation.