Index: openacs-4/packages/acs-core-docs/www/xml/engineering-standards/docbook-primer.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/engineering-standards/docbook-primer.xml,v
diff -u -r1.11.2.5 -r1.11.2.6
--- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/docbook-primer.xml 18 Nov 2004 20:27:54 -0000 1.11.2.5
+++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/docbook-primer.xml 20 Nov 2004 05:08:56 -0000 1.11.2.6
@@ -364,7 +364,7 @@
description, current version, implementation status,
author/maintainers, link(s) to more info. Current version
available at the Package status page.
+ url="http://openacs.org/repository/5-2/">repository.
Include dependencies/requirements, known conflicts, and
@@ -383,7 +383,7 @@
supported by the current e-commerce module? There are some
packages where the name is clear enough, but what are the
limitations of the standard package?
-
+
End-user docs should not be duplicative. The package
description information and almost everything about a
@@ -397,8 +397,96 @@
-
+
+ OpenACS Documentation Requirements for Site and Administrators
+
+ By the OpenACS Community. This section is a collection of
+ documentation requirements that have been expressed in the
+ OpenACS forums to 4th July 2003.
+
+
+ OpenACS administrators' documentation should meet the following goals. No
+ significance has been given to the order presented, topic breadth or depth here.
+
+
+
+ For each requirement below, include links to developer tutorials
+ and other documentation for more detail.
+
+
+ Describe a structural overview of a working system and how
+ the components work together. "The Layered Cake view" a
+ general network view of system; a table showing system
+ levels versus roles to help with understanding how the
+ subsystems are interconnected.
+
+
+ Provide a comprehensive description of typical
+ administrative processes for operating an OpenACS system
+ responsibly, including reading logs and command line views that
+ describe status of various active processes.
+
+
+ Create a list of administrative tools that are useful to
+ administrating OpenACS, including developer support,
+ schema-browser and api browser. Link to AOLserver's config
+ file documentation.
+
+
+ Resources on high level subjects such as web services,
+ security guidelines
+
+
+ Describe typical skill sets (and perhaps mapped to
+ standardized job titles) for administrating an OpenACS
+ system (human-resources style). For a subsite
+ admin/moderator attributes might include trustworthy,
+ sociable, familiarity with the applications and
+ subsystems, work/group communication skills et cetera
+
+
+ Describe how to set up typical site moderation and
+ administration including parameters, permissions, "Hello
+ World" page
+
+
+ Show directory structure of a typical package, explanation
+ of the various file types in a package (tcl,adp,xql) and how
+ those relate to the previously described subsystems, when
+ they get refreshed etc.
+
+
+ Ways to build a "Hello World" page
+
+
+ Show examples of how the OpenACS templating system is used,
+ including portal sections of pages. For example, create a
+ customised auto-refreshing startpage using lars-blogger, a
+ photo gallery, and latest posts from a forum. This should
+ rely heavily on documentation existing elsewhere to keep
+ current. This would essentially be a heavily annotated list
+ of links.
+
+
+ Show ways of modifying the look and feel across pages of an
+ OpenACS website. Refer to the skins package tutorial.
+
+
+ Describe a methodology for diagnosing problems, finding
+ error statements and interpreting them --for OpenACS and the
+ underlying processes.
+
+
+ FAQs: Administration tasks commonly discussed on boards:
+ admin page flow, how to change the looks of a subsite with a
+ new master.adp, options on "user pages" , a quick
+ introduction to the functions and processes. info about the
+ user variables, file locations
+
+
+
+
OpenACS Documentation Strategy: Why DocBook?