[Using Sakai] sakai-user Digest, Vol 19, Issue 31
Smart, Whitten J
ws15 at txstate.edu
Wed Sep 29 13:42:17 PDT 2010
We at Texas State have developed our own customized documentation, videos, FAQ, and searchable knowledgebase (the "how do I" questions) for both faculty and student users. All of our information can be found at http://tracsfacts.its.txstate.edu
Regards,
Whitten Smart
User Services Consultant II
ETC Support
Texas State University - San Marcos
------------------------------
Message: 2
Date: Wed, 29 Sep 2010 14:45:05 -0400
From: Gayle Stein <gstein at rutgers.edu>
Subject: Re: [Using Sakai] End-User Documentation
To: Nicola Monat-Jacobs <nicola at longsight.com>
Cc: Robin Hill <Hill at uwyo.edu>, URI Discussions about Sakai
<SAKAI-URI at LISTSERV.URI.EDU>, "sakai-user at collab.sakaiproject.org"
<sakai-user at collab.sakaiproject.org>, Marshall Feldman
<marsh at uri.edu>, "Charles A. Collick" <ccollick at oit.rutgers.edu>
Message-ID: <4CA38931.6010000 at rutgers.edu>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
All:
A number of years ago, Rutgers was involved in a community-wide group
that was trying to accomplish the same thing that you are; I don't have
a clear memory of what happened with the group. But we thought that
end-user documentation was important, since we are supporting 40,000
active users per week with 3 FTE staff and about 1 FTE student staff.
So we developed a complete set of end user documentation,incorporating
local changes. Many schools, at that time, asked if thy could take our
documentation and customize it for their own use. And at least a few did.
We use student staff to make most of the annual documentation changes,
after they have helped us with QA. We have found that, after the QA,
they are well-positioned to make all relevant changes.
And this past summer, we developed a second set of end user documents,
called "How do I. . ."
You can see the documentation in the Help section at sakai.rutgers.edu.
Please feel free to get in touch with Charlie Collick at Rutgers for
more information about how we developed both types of documentation and
for access to the original files.
--Gayle
Gayle K. Stein, Ph.D.
Associate Director for Instructional Technology
Office of Instructional and Research Technology
Rutgers, The State University of New Jersey
On 9/29/10 1:51 PM, Nicola Monat-Jacobs wrote:
> 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.
>>
>> 1. 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.
>> 2. 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.
>> 3. In the open source world, documentation standards and tools are
>> common. For example, the R Project for Statistical Computing
>> <http://www.r-project.org/> 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.
>> 4. 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.
>> 5. 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.
>> 6. 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.
>> 7. 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.
>> 8. 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.
>> 9. 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 <http://www.diigo.com/>. 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.
>> 10. 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-8508http://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
>> CUSR Logo
>> 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
>> <mailto: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"
>
>
>
> _______________________________________________
> 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"
------------------------------
_______________________________________________
sakai-user mailing list
sakai-user at collab.sakaiproject.org
http://collab.sakaiproject.org/mailman/listinfo/sakai-user
End of sakai-user Digest, Vol 19, Issue 31
******************************************
More information about the sakai-user
mailing list