Also my first post, although I've been lurking about for quite a while.... I guess I've found a topic I feel I can contribute something to.
First, I want to quickly mention that I deeply appreciate the OpenACS community and all that has been accomplished by the people who have given so much of their time. Thank you! I certainly hope to reciprocate.
End-user documentation is critical to the success of my own OpenACS project, so I would be very interested in combining efforts with anyone else who has the same needs. Dan's last post hit the nail on the head. I've found that although I'm no technical genius, most of the people that I have been dealing with in trying to make these projects happen, often decision-makers, are less technical than myself.
I would love to work together on documentation, but am I stating the obvious in saying that collaborating on documentation shares some of the major challenges with collaborating on software development? The three issues that immediately come to mind are
1) Establishing and adhering to standards
2) Managing contributions and revisions
3) Managing the (editorial) release cycle
The two end-user documentation projects that I've had in mind are
1) Module documentation - Perhaps using the existing documentation as a starting point to provide:
a) A description of WHAT each module is, what it does, any functional dependencies, one or more examples of how it adds value to a site, etc.
b) Instructions on HOW to use it, what's required to implement it (whether or not it's ready to use "out-of-the-box"), how it's administered on an on-going basis, what kind of maintenance is required, etc.
2) A Glossary of (Open)ACS and possibly other technical terms - Identify and explain terms that an end-user might not have in their vocabulary. It's easy to take for granted that a reader is familiar with a term like "Tcl", and a certain level of knowledge may need to be assumed, but having a place where a reader can go to quickly look up an explanation, placing it in the context of the OpenACS, could greatly extend the accessibility of the documentation.
Some redundancy in documentation can also be a good thing, because it's easier to find an answer if it exists in more than one place. So in putting together a FAQ, for example, there will probably be parts of that text that could be repackaged and incorporated into other documents.
I guess the first step is to know what the starting point is. I haven't written any of this yet, so I was going to start from the standard documentation. I would be happy to contribute either to a new documentation effort or to any project that is already underway.
Walter
