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

My first post to OpenACS... I'm nervous... :->

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!

Your first post??? Get out of here! ;)

Seriously, welcome Dan. Glad to hear you're using The System.

I think you're idea sounds great. So far the community has been almost exclusively techie, so there has been little user experience documentation or discussion. There is a fairly good amount "hard coded" into the software, but I think you're right. There ought to be some general guidelines for how best to lay out the system for design and functionality.

Generally, people have been referred to or been offered a quote from Jakob Nielsen. That's usually a very good starting point. But something OpenACS specific is a great idea.

What did you have in mind? I imagine that you're not really talking about graphic design as much as user interface, if there is a difference, right? I mean, not really about fancy pictures but how to get the layout the system to allow the user to get the most out of it.

Am I right?

talli

Hi Dan, welcome aboard and be welcomed!

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.

Actually Talli...I'm guessing that Dan is mostly talking about text instructions, not UI or graphic design at all. Am I right Dan? I agree that there's almost NOTHING out there for the end user. That's a great idea to start building on.

As far as graphic design and UI go...I'm willing to do my part there. Just point me in a direction!

Scott

Scott, that's a good point. I think I misread what Dan was talking about. However, I think my point was good too. ;)

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

Thanks for the clarification Scott;  indeed, I am referring only to text instructions aimed at users. Pretty much everything written down so far seems to be aimed at developers (and assumes semi-developer knowledge or better). For OpenACS in general to catch on more, and for each of our individual sites to be successful, user support materials will be very important.

The top item on my wish list is to get an FAQ.  I don't know how many OpenACS and ACS systems there are, but I sure hope there's at least one FAQ "out there" that someone will allow me to use as a starting point.

Also, developers may be putting some helpful information directly on registration pages, option-setting pages, etc. to correct or supplement ACS screen prompts/explanations. I'll start a separate thread "Screen Instruction Errors/Ambiguities" to collect these... that may be helpful to developers for immediate use and to the OpenACS team for future revs.

Thanks... I'm really jazzed about OpenACS!!

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

Okay, maybe it wasn't my *first* post, just my first "serious" post, or my first post this year, or something like that....
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...