Forum OpenACS Q&A: FAQs and/or basic User information/documentation

I have an OpenACS site launching in a few weeks, and the ACS user
help documentation seems... um... lacking.

I want to gather some basic user documentation (including FAQ
information if possible!!) and make it available both on my site and
to everyone else in the OpenACS community.

My site will be on 3.24, but I expect 95% of what I would write up
would be relevant to everyone. As examples:

  1) Janine at Furfly tells me that everyone writes their own
paragraphs explaining how and why cookies are used. This may be a
trivial example, but it's really surprising to me given the open
source philosophy of OpenACS.

  2)  Michael Feldstein's recent posts about new users not knowing
how/whether to register before posting.

So... I think it would be very handy to have a whole set of such
explanations available to all of us as a building block, and of
course those who wish can customize or delete as they see fit.

    1) Does anyone know of an OpenACS FAQ that I might get permission
to use as a building block for this effort?

    2)  Assuming #1 above is too good to be true... If you can
contribute any helpful explanations, or point out any topics that
need such write-ups, it would be very much appreciated.

Thanks!

Why are you using 3.2.4 instead of 3.2.5? Many fixes and enhancements went into 3.2.5, including in the ecommerce area.

As for cookies and sessions, you might want to read the documentation, included on your copy of OpenACS and at openacs.org (https://openacs.org/doc/security-sessions.html

On 2), that's more of an issue on our site (that has been fixed BTW), not really the toolkit.

If you could write a FAQ to be included as part of our "Getting Started Guide" then please, by all means. It would be a great addition and help.

I think that a common FAQ for how people use OpenACS community's is a great idea. What I was also thinking, and this is from a developer's perspective, is that perhaps we ought to gather experience for designing interface for the OpenACS and create a "best practices" FAQ for designing these communities.

I mentioned that much of the UI is hardcoded into the software, but there is still plenty of leeway for improving it or implementing it for the entire site or a case by case basis. This can be done individually by each developer by swinging through all the openacs sites and collecting their favorite ideas, but it might be neat to have some UI designers chime in about how they approached the challenge and why.

Scott, I'm assuming you're volunteering?

talli

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

Now that I'm vaguely caught up from vacation, a few comments:

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

You're thinking is more advanced on this than mine is! #1 is a for sure, some thought about this up front would be smart. As for #2 and #3... I think we should start out with a first pass and then see what happens. Since it's somewhat looking like it's just we two for now, I think a less formal process is OK here where it wouldn't be for a software development project.  But I've never coordinated on a a group documentation project, so if you have more experience with such things....

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

"a" seems very urgent and safe... much of the rest may be more dependent on which version is being used. I'm thinking maybe a first pass at "a" and then fill out the rest later.

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

Agreed, would be very helpful. Off the top of my head, I wonder if a glossary might be done 'ad hoc' via the openacs site, ie. (i) people submit terms to be defined, (ii) one or more community members submits responses, (iii) an knowledgeable editor distills the responses and posts an official definition.

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

With documentation, "redundancy" makes me think immediately of  maintenance headaches.. but if by redundancy you mean admin documentation separate from user documentation, then YES!!

I'm willing to put in some hours on this work... but my technical knowledge base is pretty shaky, so my contributions are probably best focused on editing, guru interviewing, etc.

We can talk...