Forum OpenACS Q&A: Response to Documentation Update (IMPORTANT)

Thanks for the update Roberto. Here are some of my initial thoughts.

• I agree with your decisions on which of the items deserve critical path consideration. I think that it's also clear that the Installation Guide and the ACS Core Docs items are the most important since those are the only projects that have writers now.

• For the Installation Guide, from what Vinod has written so far it seems that his work is based on Debian, right? That's fine. I guess that can be the more or less canonical guide for installing the OACS. However, there is a bit of a difference in configuring the various Linux distros, not to mention the differences between installing it on the BSDs and on Windows.

  I recommend that we have the canonical version that Vinod has written as the primary install guide and then offer various other install guides for each OS and each Linux distro. So the layout would be:

  • Vinod's Canonical Install Guide (Debian Linux?)
    • Linux
      • Redhat 7.x
      • Redhat 6.x
      • Suse
      • Slackware
    • Windows
      • Win2K
      • WinXP
    • Gilbert Wong's FreeBSD Guide as the canonical guide for BSD
      • OpenBSD
      • NetBSD
    • Walter McGinnis' MacOS X Install Guide

• What does the ACS Core Docs consist of actually? Does this item represent all of the packages in the system? Do we need to find volunteers to maintain the docs for each package and/or module?

• The Query Dispatcher doc, Object System doc and the Permissions doc are all fairly hairy pieces of literature, right? What kind of documentation needs to be written, and who will the intended audience of these pieces be?

  I think that these are pretty critical to cover. When you say that the Object System docs and the Permissions docs are to simplistic, do you mean that they were written for beginner's or that they are too superficial? I assume that you mean that they are too superficial since you ask for more detail and examples, but it may be important to write at least part of the docs for beginner's. Is this right?

• Since the Beginner's Guide is already being written to a degree (I know that David Geilhufe is surely doing it, and perhaps Tapiwa is adding some pieces as well) perhaps we should put this item on the fast track as well?

• I think that it might be a good idea to define a certain style for the docs. What I am referring to is not necessarily the style definitions described in the XML or SGML Docbook sources, but how to word certain things and what items need to be included in a "complete" piece of documentatoin.

  For instance, I think that a complete piece of documentation for a package would include:

  • Exec Summary or Introduction This would be a short introduction to what the package is, what it does, where it should be installed, etc. Just a summary of what is to come. Somewhat like the "Big Picture" piece of previous ACS docs, but more complete. In fact, I like the way Neophytos and Kapil called this section "A Hitchhikers Guide to ..." in the docs they wrote for the ACS Service Contract.
  • How to install This could very well consist of "Go here and download the APM" but it should include whatever the process is.
  • How to configure What files need to be configured, where the files are, what possible problems need to be looked for, etc.
  • How it works A description of the guts of the application, package or module.
  • Troubleshooting tips This item could be implemented in a couple of different ways, from general comments to a Wiki-esque app using ETP or Jerry Asher's wiki application. Basically, it should be a page where people can add their experiences of fixing or troubleshooting applications, packages or modules. It should also provide a way to link to appropriate bboard threads where the package was discussed.

• How about the ACS Service Contract stuff? I understand that it is becoming an important piece of the system, and will continue to be so if for no other reason than OpenFTS uses it. I know that Neophytos and Kapil have written something up very quickly that solves most of the problem. I also understand that OpenForce used the ACS-SC pretty heavily in dotLRN.

Those are some of my initial ideas. What do you (and others) think?

talli