[Using Sakai] End-User Documentation

[Robin Hill]

Dr. Feldman--

As something of a newcomer, I understand your frustration.  As I become a mid-timer, I see the situation more clearly.  

Sakai is not a monolithic product with a central documentation team.  Sakai is a cordial family of instances that differ somewhat in their configuration and implementation, to suit the purposes of the particular organization.  The open-source components are the software and its interfaces and the Help files, and they are tailored and integrated on installation.  That's why the best resource for faculty is the institution's own experts.  

As for your questions , both of these issues have come up recently at my university, and I am happy to share our results with you, insofar as they apply.  

The answer to the Schedule/Calendar question is still emerging-- apparently one of our ".csv" files (exported from MS Outlook, I believe) contained extraneous line breaks.  But most comma-separated values files will import (as the "generic" type) successfully.  

As for the Tests & Quizzes metadata, those fields "Objective," "Keywords," and "Rubric" are for instructor purposes, and only appear on that screen (the edit page for the individual question), so issues on delimiting and case-sensitivity are moot.  Although included with a view to future retrieval or other processing, that has not yet developed. 

For official documentation, if local help is not open to you, your best bet is to follow the suggestions already given:  Peruse the larger institutions' documents.  Many are quite good.


--
  Robin K. Hill, Ph.D.      Coordinator of Instructional Computing, University of Wyoming
  [On professional leave, 2010-2011]
  hill at uwyo.edu        307-760-8508     http://www/uwyo.edu/ctl
________________________________________
From: sakai-user-bounces at collab.sakaiproject.org [sakai-user-bounces at collab.sakaiproject.org] On Behalf Of Marshall Feldman [marsh at uri.edu]
Sent: Wednesday, September 22, 2010 7:41 AM
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."
 4.  What does the Schedule tool want in a csv file for all-day and multi-day events?
 5.  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?
 6.  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.)
 7.  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