Forum OpenACS Q&A: Documentation questions

Collapse
1: Documentation questions
Posted by Roberto Mello on 05/03/00 10:46 PM
These are some issues I want to bring up to the team. Please don't
get me wrong, I think Greg's docs are great.

    I've been looking at Greg's Concrete Guide and it seems to me that we
have redundant and possibly confusing documentation. There is a lot of
information that is present in both the Concrete Guide and the
Installation and Configuration guide. If you were a new user, which
one should you start reading ?

    For example, the .tcl initialization files issue will be included in
both the Install Guide and the Configuration Guide. More dangerous is
that fact that having the same thing documented twice opens space for
errors in one, another or both.

    My proposed solution to this is unify the Install Guide with the
Concrete Guide, making it an Installation and Configuration Guide that
is concrete by itself. That way I and Greg would work together
reviewing each other's work.

    The next thing we could work on it terms of documentation is to
create a FAQ for OpenACS, so we don't have to answer the same
questions over and over.

    Another thing I thought of doing is to create a "OpenACS Quick
Reference" PostScript file that would have the ACS-specific procs and
utilities. This could be done using HTMLDOC. Yes, all this can be
accessed in /doc, but for me it's much faster to open up a reference
guide than to open another browse window, click on "sort by name", and
then scroll to find the proc I am looking for. This would help in
facilitating the creation or improvements of modules. I want to create
a PS file for the AOLserver API as well (but this is off-topic).

    Suggestions, thoughts ?

    -Roberto
Collapse
2: Response to Documentation questions (response to 1)
Posted by Noel Welsh on 05/11/00 12:04 PM

I agree that the current documentation should be combined. The things I'd like to see in the documentation are:

  1. An installation guide, based on the result of merging the current documentation. This guide should provide indepth coverage of installing the ACS, and possibly AOLserver and Postgres. It should illustrate the installation process with a concrete example (the "books" example Greg uses, but I really think it should be called DeadTrees 😊.
  2. A quick install guide for the impatient. This should be a simple document or script that will install the DeadTrees example used in the complete installation guide. This is to get something up and running fast, so people will have something to play with.
  3. A using the ACS guide, that details how to get things done with the ACS. E.g. how to set up a bulletin board, the SDM, whatever. This is quite ambitious, so I can't see it being done anytime soon. However, an FAQ could evolve into such a beast.

I suggest starting with the complete install guide first as it offers the greatest return on investment. Lots of the above is generic to the ACS, so we could reuse existing documentation and collaborate with aD if they head in the same direction.

Collapse
3: Response to Documentation questions (response to 1)
Posted by Don Baccus on 05/11/00 04:09 PM
I've written a first cut at much of the above, for InformIT, a MacMillan website.  Don't know much about them but they were looking for pieces on Postgres-related stuff, and I figured we could use the exposure.

I can't use the stuff directly, but my plan is to redo the pieces, and include more examples, for our use.  This will take some time, though (my endless "I'm busy" whine :)  Maybe in a month or so.  Until then, once they are up on InformIT we can reference them.

The pieces include a quick example of setting up a bulletin board, with screenshots, etc.  Unfortunately, they refer to "ACS/pg", but I think I'll get a shot at doing some editing once their editor reviews them.  They're in the pipeline, not sure when they'll pop out the other end (if you've worked with publishers before, you'll recognize this suspended-animation state I'm describing for the articles).

Collapse
4: Response to Documentation questions (response to 1)
Posted by April Johnson on 05/22/00 05:36 PM
Two things that would be great to see:

1. A fairly comprehensive FAQs page, definitely.
2. For relatively non-technical types (ie myself), a features list (maybe as part of the FAQs) that gets updated with each version. This would be wonderfully helpful for anyone trying to "shop around" for tools.

~april