[Using Sakai] End-User Documentation

Wed Sep 29 15:24:12 PDT 2010

The End-User Support group, home to some of the pages that Dr. Feldman has seen, lacks a leader.  No activity has taken place in that space for some time.

I've just done some updating on the main End-User Support page, showing the faculty documentation sites kindly suggested by Oxford, Rutgers, and Texas State, in response to this thread, and also labeling some of the sections with more detail.

Sean, as a start, perhaps the best move would be to revive that group, with regular meetings (conference calls) and reviews of the institutional documentation already submitted on those pages.  Suggestions from others?

--
  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 Sean Keesler [sean.keesler at threecanoes.com]
Sent: Wednesday, September 29, 2010 4:17 PM
To: Mathieu Plourde
Cc: Regan, Alan; sakai-user at collab.sakaiproject.org; Marshall Feldman
Subject: Re: [Using Sakai] End-User Documentation

We tried to generate some interest around building some simple screencasts for the sakaiproject.org<http://sakaiproject.org> site at the Denver conference. Sort of a similar concern...

http://confluence.sakaiproject.org/display/CONF2010/Screencasts+for+sakaiproject.org

A couple people were interested in helping, but no one really has done anything yet.
This could/should be part of something larger.

I'd like to contribute some time to a managed docs project. Is it time to rally round the topic and form a working group?

Sean

On Wed, Sep 29, 2010 at 5:08 PM, Mathieu Plourde <mathieu at udel.edu<mailto:mathieu at udel.edu>> wrote:
Hi Marshall and all,

This issue of documentation has been around for a while. A presentation from folks at Perpperdine in Denver captured some of this, as well as one I was involved with in Boston the year before.

http://confluence.sakaiproject.org/display/CONF2010/Sakai+Community+Documentation

Alan Regan asked attendees to sign-up through a web form. I don't know if anything was initiated after that, but I'd love to know more!

Mathieu

On Wed, Sep 29, 2010 at 3:20 PM, Marshall Feldman <marsh at uri.edu<mailto:marsh at uri.edu>> wrote:
Thanks, Nicola. I do have an account.

But I looked on the wiki and listed the "complete list of Confluence spaces." I searched the page for "document" and had a few hits: Documentation, Nakamura Documentation, OSP Documentation, Project: Messages & Forums, WG: Accessibility, and WG: Production (deploying Sakai). I am unfamiliar with Nakamura and OSP, so the Documentation space seemed most appropriate.

The listing described the space as follows: "This space contains official documentation on Sakai, while also exposing the revision process to public comment and criti..." So I clicked through. Once in the space I saw "Release Documentation," which I presume is release notes. Below it, I saw "Other Documentation," under which was "End-User Support Documentation." There is also a link for "Documentation Standards," about which I'll say more below.

The "End-User Support Documentation" includes training, tutorial, and consulting resources. It also has a resources for end-user support staff and a set of presentations with Sakai support orientation. The only part that speaks directly to the issue I'm raising is the section entitled "Documentation Resources," which consists entirely of customized help pages and the like (including tutorials here rather than under Tutorial Resources). All of the latter are contributed by nine different universities, and there seems to be a great deal of duplication. None of the contributors is identified as the "official" entity charged with writing the documentation.

The section on "Documentation Standards" talks almost entirely about the electronic format used for the documentation (e.g., DocBook versus HTML). It does say, documentation "should be easy for developers to write, or volunteers to contribute, without a significant learning curve" but it says absolutely nothing about documentation from the point of view of end-users. It does not even prescribe a standard layout for documentation, such as one finds for Unix man pages.

I don't see where one can participate in a conversation about documentation, mainly because there does not seem to be a conversation going on. I did, however, leave a comment on the documentation standards page.

As for your suggestion that I get involved, I find it flattering but would not know where to begin. I am just an end user and have very little understanding of how Sakai works both as an organization and technically. For example, I have no idea if the Help pages are just linked HTML documents, or does Sakai process them so they can be updated in real time? Furthermore, this is so far removed from my job responsibilities that I could not justify it. As someone who teaches online, I depend on a good LMS, but I can no more justify becoming heavily involved in its design and delivery than I can justify becoming involved in the design of the furnace that heats my office.

    Cheers,
    Marsh Feldman

On 9/29/2010 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<mailto:hill at uwyo.edu>        307-760-8508     http://www/uwyo.edu/ctl
________________________________________
From: sakai-user-bounces at collab.sakaiproject.org<mailto:sakai-user-bounces at collab.sakaiproject.org> [sakai-user-bounces at collab.sakaiproject.org<mailto:sakai-user-bounces at collab.sakaiproject.org>] On Behalf Of Marshall Feldman [marsh at uri.edu<mailto:marsh at uri.edu>]
Sent: Wednesday, September 22, 2010 7:41 AM
To: URI Discussions about Sakai; sakai-user at collab.sakaiproject.org<mailto: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><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><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><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><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><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

--
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<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<mailto:sakai-user-unsubscribe at collab.sakaiproject.org> with a subject of "unsubscribe"

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

Center for Urban Studies and Research<http://www.uri.edu/prov/research/urbanstudies.html>
The University of Rhode Island<http://www.uri.edu>
email: marsh @ uri .edu (remove spaces)<mailto:marsh%20%5C%20uri%20.edu>
Contact Information:
Kingston:
202 Hart House
Charles T. Schmidt Labor Research Center<http://www.uri.edu/research/lrc/>
The University of Rhode Island<http://www.uri.edu>
36 Upper College Road
Kingston, RI 02881-0815
tel. (401) 874-5953:
fax: (401) 874-5511
Providence:
206E Shepard Building
URI Feinstein Providence Campus<http://www.uri.edu/prov/>
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<mailto:sakai-user-unsubscribe at collab.sakaiproject.org> with a subject of "unsubscribe"

--
=================================

Mathieu Plourde, MBA
Project Leader, LMS/Instructional Designer
IT-Client Support & Services
mathieu at udel.edu<mailto:mathieu at udel.edu>
Office: 302-831-4060

=================================