[Using Sakai] End-User Documentation

[Adam Marshall]

http://wiki.oucs.ox.ac.uk/weblearn/SakaiAdministratorFaq#head-a85e5391d85826a3fcced72ddec175b42fdd82e2 this may help you on some points.

we also have a whole heap o' material at weblearn.ox.ac.uk/info

adam
From: sakai-user-bounces at collab.sakaiproject.org [mailto:sakai-user-bounces at collab.sakaiproject.org] On Behalf Of Marshall Feldman
Sent: 22 September 2010 14:42
To: URI Discussions about Sakai; sakai-user at collab.sakaiproject.org
Subject: [Using Sakai] End-User Documentation

Hi,

Is there any good, detailed, "official," end-user documentation for Sakai's tools? The standard Help files often give only the most superficial information.

Here are examples of the kind of questions for which I'm looking for answers:

 1.  The Schedule tool can import files formatted for Microsoft Outlook, Meeting Maker, iCalendar (iCal), and a generic calendar import (comma-separate values), but it seemingly can only export iCal ics files. Is this correct? If so, what is the Sakai-recommended method for exporting Sakai schedules to the other formats?
 2.  The specification for iCal files<http://www.ietf.org/rfc/rfc2445.txt> is complex. So it's not clear how Sakai converts the Schedule information into an ics file. For example, the specs allow for different "user types" (individual, group, etc.), but how does Sakai treat a calendar entry for a course? More generally, where does Sakai document what it exports in an ics file?
 3.  Where is the documentation for the csv file format that Sakai can import? I found some unofficial documentation<http://www.google.com/url?sa=t&source=web&cd=7&ved=0CDIQFjAG&url=http%3A%2F%2Finfo.t-square.gatech.edu%2Ffiles%2Fimport_calendars.pdf&rct=j&q=sakai%20schedule%20import&ei=c3yZTKuhIoP6lwebrIXsDw&usg=AFQjCNHuAlayqbCZVCZ3_twugo80RQOOJg&sig2=n90eWSZTyVs2guRy-3H8vQ&cad=rja>, but it's incomplete. For example, can one include HTML in the fields? Similarly, the csv format encloses strings in quotation marks, but is there an escape character to tell Sakai to treat certain strings differently? For example, how should one code the following text?
Come to class prepared to compare and contrast William J. Wilson's Declining Significance of Race with at least two more recent theories of "race."

 1.  What does the Schedule tool want in a csv file for all-day and multi-day events?
 2.  There's some ambiguity associated with such things as noon and midnight, as well as multiple standards for dates and times. What standard does Schedule use?
 3.  A similar set of issues arises with the Tests & Quizzes tool. For example, it allows keywords for question pools, but what delimits a keyword? Suppose for example that someone is teaching a course on race and wants to use the following keywords (delimited here by curly brackets): {Martin Luther King, Jr.}, {race}, and {"race"}. (In the literature on race, "race" with the quotes is used to indicate that "race" is primarily a social construction that misapprehends nature whereas race (without the quotes) indicates a more sanguine usage that treats the concept as if it referred unambiguously to something found in nature.)
 4.  Similarly, are keywords case-sensitive?
All I can find in the standard Sakai (2.6) help regarding such questions are the following statements:

 *   Under Importing a Calendar: "Click the radio button beside the type of calendar file you are importing (Microsoft Outlook, Meeting Maker, or Generic calendar import (comma-separate values)), and then click Continue."
 *   A search in the Help for "keyword" returns three items: "Advanced Search," "Modify Assessment," and "Working with citation lists." Only the second pertains to the T&Q tool, but all it says about keywords is "Modify the "Objective", "Keyword", and "Rubric" metadata fields"  (thanks a lot). Furthermore, although it does not show up in a search for "keyword," the Adding, moving, copying, or removing a question pool or subpool entry does have this similarly superficial information: "In the optional "Keywords" field, type any keywords that may help you or someone else locate this question pool."
Searches on the Sakai wiki<http://confluence.sakaiproject.org/display/CONF/Welcome+to+the+Sakai+wiki> yield almost 400 hits for "Schedule" and 250 for "keyword." Many of these, probably most, are of more interest to Sakai developers than end-users. Also on the wiki, there's a section dealing with "Using Sakai<http://confluence.sakaiproject.org/display/CONF/Welcome+to+the+Sakai+wiki>," but in that section the one item that seems geared to answering questions such as those above is called "End User Support Aids: A collection of end-user support materials and information<http://confluence.sakaiproject.org/display/ESUP/End-User+Support+Working+Group>." Clicking through, one finds a section containing documentation, but it is at such a high level that answers to questions such as those above are akin to finding needles in haystacks. Currently there are ten entries of contributed items, the most relevant of which have titles like "Custom Help Pages & FAQ."

It shouldn't be this difficult. All I'm looking for is what in the old days of IBM mainframes used to be in documents called "User Guides" and "Reference Manuals." Is there an easier way to find "official" answers to questions such as those above?

Thanks.

    Marsh Feldman

Dr. Marshall Feldman, PhD
Director of Research and Academic Affairs

Center for Urban Studies and Research
The University of Rhode Island
email: marsh @ uri .edu (remove spaces)
Contact Information:
Kingston:
202 Hart House
Charles T. Schmidt Labor Research Center
The University of Rhode Island
36 Upper College Road
Kingston, RI 02881-0815
tel. (401) 874-5953:
fax: (401) 874-5511
Providence:
206E Shepard Building
URI Feinstein Providence Campus
80 Washington Street
Providence, RI 02903-1819
tel. (401) 277-5218
fax: (401) 277-5464
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://collab.sakaiproject.org/pipermail/sakai-user/attachments/20100922/798efc16/attachment-0001.html