Forum OpenACS Development: user documentation

1: user documentation

Posted by Rafael Calvo on 06/27/01 06:31 AM

How can we improve user help documentation?

openACS actually has a lot of stuff at the admin/ developer level, but we are lacking good manual pages at the user level.
I will be porting calendar and woudl like to have something like Yahoo!
I could just write one or more adp pages, using the standard headers and footers, by it might be good if we can standarize the presenation and format across modules.
I apologize if I missed any concrete proposal that might be in other threads.

2: Response to user documentation (response to 1)

Posted by David Kuczek on 06/29/01 09:45 AM

Why don't we use the faq module on this. Yahoo's design is just a little bit better than ours, but the features are basically all covered by faq.

3: Response to user documentation (response to 1)

Posted by Michael Feldstein on 06/30/01 04:08 AM

Interesting.

There's something important here about scoping for both FAQ
and glossary. I seem to recall that at least one of these two
modules was designed, in it's 4.x incarnation, to be scoped even
for individual pages. An FAQ module scoped like that would be
an outstanding basis for context-sensitive help. We could tweak
the interface a bit but, as David suggests, I think the default
would probably work OK.

4: Response to user documentation (response to 1)

Posted by Rafael Calvo on 06/30/01 04:49 AM

Using faq for the user documentation would add it as a dependency on the whole toolkit. Is this a good thing?

I haven't used faq. How would the usability work?. I like the idea tha the user can go to openacs.org/help/calendar or something he can find the user help.
typing :
http://openacs.org/faq/one?scope=public&faq_id=6

is not very memotecnic. In fact linking from each package directly to the module help would be cumbersome (you would need the faq_id)

5: Response to user documentation (response to 1)

Posted by David Kuczek on 06/30/01 05:29 PM

We are using faq very extensively and it works really great. The answers are all being displayed as html, so you can use links a lot and directly redirect users to the right location. The only difference between Yahoo Help and faq is the fact that you cannot display the questions on one page seperately. But it shouldn't take more than an hour to add this feature (if you really want to add it).
We could copy the /faq/* code to /help/ and call it help. On /help/index.tcl you would see the different module names and could easily click on the one you are seeking help for.

Maybe you could alter the data modell and add a column faq_type varchar(20) or something like that, where you could choose wether the text was a real faq or a help issue. Then you could display only the help issues on /help and the faq issues on /faq.

I think that faq offers everything you need. You could additionally activate general-comments and improve the help step by step. You can add people to the faq group so that not only the site-wide-admin can add a faq-question or alter an faq-answer but every member of that group.

6: Response to user documentation (response to 1)

Posted by Rafael Calvo on 07/02/01 12:36 AM

David, Don't get me wrong, I do like the idea. But the three issues still bug me:

Usability: It would be nice to have the help parameters passed as directories, so users could remember (no matter where they are) that typing domain.com/help/calendar the get the help for calendar. The usability could be solved passing $scope and $faq_id with two "/", and then parse it back to the original variables.
Development. faq_id is needed to write a link, so if you are writing the module calendar, you need be aware of the faq_id for it. Maybe changing the data model can instead of using a numeric faq_id using a string?
Dependency. faq or help (however you want to call it) would be part of the core openACS, every module would depend on it. I think its fine, but there might be impliecations I am not aware of?