[Using Sakai] End-User Documentation

Wed Sep 29 10:51:19 PDT 2010

Dr. Feldman -

I think the Sakai community will universally agree that Sakai documentation could be better - you'll get no argument from me there. I think the problem is lack of resources and time (both to write documentation or to put in place some of the documentation-insuring policies that you lay out below). From your passionate and well-researched argument, I can tell that you'd be a great asset to the Sakai documentation effort. One of the benefits of open-/community-source, is that if you find something is broken, you have an opportunity to fix it! 

What generic Sakai documentation does exist lives in the Sakai confluence wiki:

http://confluence.sakaiproject.org

Do you have an account there?

I encourage you to make contact with like-minded folks (such as you have already done on this list) and work with the Sakai committees already in place to achieve your desired goals.

Thanks,
Nicola

On Sep 29, 2010, at  7:39 AM, Marshall Feldman wrote:

> Dear Robin Hill,
> 
> Thanks for the explanation. I asked the same question on our local listserv and got a very similar answer. So I suppose this is the way the Sakai world is, just as world hunger is a regrettable reality in the larger world. However, just like world hunger, this is (or should be) unacceptable. Here are some reasons why.
> Despite differences in configuration and implementation, local institutions typically implement tools developed elsewhere. These tools need to come with proper documentation. If the local institution modifies the software or implements it in a non-standard way, then the local institution needs to document its changes.
> There is a long history of this kind of thing, and Sakai is not unique. From 1969 to 1971, I was a systems programmer at MIT. We made numerous changes to the raw code IBM provided us, but IBM always provided extensive documentation and we always documented our changes. IBM had a user's organization called SHARE which, as its name suggests, shared software, customizations, and solutions. SHARE had documentation standards. So being a loose federation is no excuse for Sakai.
> In the open source world, documentation standards and tools are common. For example, the R Project for Statistical Computing provides a base product to which users commonly add extensions called "packages," of which there are literally thousands. Without these packages R would be much less useful. The Project helps ensure minimal documentation standards by publishing a guide for package developers and providing software for writing packages. Both include documentation standards. Additionally, the main distribution sites for packages will not accept a package unless it conforms to the standards.
> Without official documentation from the developer, it's impossible to know if any local interpretation of the software is correct. Only the developer knows what the developer intends. Is a certain behavior intentional, or is it a bug? Our faculty support staff does not include programmers, but even if they could read the Java code, they could only tell where the software causes a certain behavior, not whether or not the behavior is deliberate.
> The current situation is an incredible waste of faculty time. I often spend hours trying to track down answers to questions in the Sakai Help, then searching the Internet, then asking my local support people, only to find that nobody knows the answer. What then? (Actually, the local staff often does not reply, and I assume they are investigating when they've given up. I have unanswered questions about Sakai going back to May 2009!) Throwing darts would be more efficient.
> Similarly, it sounds as if the support staff at every institution running Sakai has to reinvent the wheel. This is an incredible waste of resources with not only unnecessary duplication of effort but also almost total guesswork since there is no definitive documentation on which the local staff can base their explanations.
> Sakai is a system designed to be used primarily by students. If an old dog like me has trouble with Sakai documentation, what's the experience for a novice user? A good LMS needs to help the faculty deliver good instruction in various subjects and otherwise get out of the way. Faculty members should not have to spend hours of their time helping students use the LMS and acting as substitutes for good documentation. The system should help students learn the material in the courses they're taking and not frustrate them because Help and other documentation are so shoddy.
> Further along these lines, one of the major roles of higher education is to enlighten. We should be teaching best practices and the right way to do things. Chaotic, incomplete, and non-existent documentation does not set a good example.
> I disagree that the issue regarding keywords, etc. is moot. Unless now and forever there will be no rules governing them in any and all Sakai software, so that individuals are free to develop their own standards, then there need to be some guidelines. Implementing software that supports all manner of user-decided conventions after the fact will be incredibly more cumbersome than stating the rules at the outset. Perhaps I use comma-delimited keywords, and my colleague down the hall uses space-delimited ones; mine are case-sensitive, hers not. Either Sakai developers will support both, or one of us will have to throw out and redo our work. Furthermore, Sakai developers probably won't be able to rely on common tools for processing keywords, since the tools will not use a common set of conventions. If this isn't reason enough, suppose someone wanted to develop a keyword hinting system similar to the excellent system provided by Diigo. The fact that the software would have to work with an unknown number of idiosyncratic and probably inconsistent rules surely would be a deterrent. We're in the second decade of the 21st century now, and Sakai should be providing similar keyword help as Diigo. But in this instance lack of a standard discourages software development. Shoddy documentation leads to shoddy software.
> One of my biggest frustrations dealing with Sakai documentation is that documentation, when it exists, often seems more tuned to system administrators and support staff than end users. Perhaps this is because, additionally, the documentation often seems to have very low expectations for end-users' technical sophistication, something I find strange for software directed at universities. In any case, perhaps there needs to be better shared governance of Sakai in which students and faculty would have a much larger role than currently. Right now technical support staff and university administrators seem to be driving the truck.
> I realize that there may be reluctance to enforce documentation standards because GUI systems like Sakai are fairly intuitive and enforcement might prevent otherwise useful tools from reaching end-users. One way to address this would be having minimal standards and a list of software meeting them. Below this, developers would have to distribute their tools outside official channels. Additionally there could be a "star" rating system with explicit standards. To earn five stars, a tool would need complete documentation (plus other things). Each tool would have its rating displayed next to it on the Site Info Edit Tools list, so course designers could be informed in their decisions to use certain tools or not. Following up on point #10, Sakai should also include a "consumer" rating system to be used by students and faculty to rate individual tools and the (local implementation of the) system as a whole. (It would also be a good idea to have something like this so students could give immediate feedback about professors' assignments, quizzes, etc. We routinely have such things for hotels, why shouldn't we have something like this on a university-generated learning system?
> 
> I hope you take this in the spirit with which it is intended. In no way do I wish to start a flame war. While I appreciate your explanation and find it truthful, I also find the current situation totally unacceptable.
> 
>     Marshall Feldman
> 
> 
> On 9/24/2010 1:40 PM, Robin Hill wrote:
>> 
>> 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 strin
>> gs 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/E
>> SUP/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
> 
> -- 
> 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
> _______________________________________________
> sakai-user mailing list
> sakai-user at collab.sakaiproject.org
> http://collab.sakaiproject.org/mailman/listinfo/sakai-user
> 
> TO UNSUBSCRIBE: send email to sakai-user-unsubscribe at collab.sakaiproject.org with a subject of "unsubscribe"

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://collab.sakaiproject.org/pipermail/sakai-user/attachments/20100929/9d949266/attachment-0001.html 