Administrators - Req.

Site and System Administrators - Documentation Requirements

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 requirements. 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