Skip to end of metadata
Go to start of metadata

Documentation for Faculty

From Instructional Visioning Ad-Hoc Discussions
E-mail discussion on sakai-user list
Driven by inquiry from M Feldman, URI.

As of October 2010, embodied in a new initiative, as per last message below.  Please see Help Files and Documentation Process Redesign

Using Sakai - End-User Documentation, Contribute to the Wiki
sakai-user-bounces@collab.sakaiproject.org on behalf of Regan, Alan
Alan.Regan@pepperdine.edu
You forwarded this message on 10/21/2010 11:07 AM.
Sent: Tuesday, October 19, 2010 3:41 PM
To:
sakai-user@collab.sakaiproject.org
Attachments:
ATT00001..txt? (344 B?)

Dear "Using Sakai" list,

As a reminder, Mathieu Plourde created a new wiki space to discuss end-user documentation. He's provided links to past conversations and resources, and more. If you are interested, please add your name and area of interest to the "Who's Interested?" table. Also, please join the brainstorming effort in the "Key Questions" section.

WHERE DO I GO?

Please visit the "Help Files and Documentation Process Redesign" wiki page at:

http://confluence.sakaiproject.org/display/ESUP/Help+Files+and+Documentation+Process+Redesign

I'M NEW TO THE WIKI...

If you want to contribute and you're new to the Sakai wiki, I put together some very quick and dirty instructions for you. (Please don't judge this redesign process by my quick effort! You can view these instructions here:

http://confluence.sakaiproject.org/display/ESUP/Contribute+to+this+Page

WHAT ARE THE NEXT STEPS FOR THIS PROJECT?

For the next two weeks, we'd like people to sign up and contribute to the key questions on the page. In early November, the group will coordinate a conference call to discuss past and current practices, discuss expectations, define roles, and create the roadmap for moving ahead with a redesign process.

Thanks, everyone, for your ideas and energy!

Sincerely,

Alan Regan, MFA

Manager, Technology and Learning

Information Technology

Pepperdine University

(310) 506-6756



On Fri, Oct 1, 2010 at 3:59 PM, Sean Keesler <sean.keesler@threecanoes.com> wrote:
I may get flamed for this...but I'm cool with that.

I've seen a few presentations at Sakai conferences about how to turn Sakai around so that it supports open courseware style work: completely public resources whatnot. However, I don't think that is Sakai's strong point. A wiki like MediaWiki is MADE for collaborative editing of PUBLIC docs. 
On the other side, Confluence seems to be geared for the ENTERPRISE (which the Sakai community isn't really) that needs to collaborate in groups and perhaps hide some info from other groups. So it's not a big surprise to me that teachers and instructional tech's haven't gotten really excited about it.

Its interesting to note that Moodle, who also has a wiki tool in their LMS, decided to run with Mediawiki for its docs site:docs.moodle.org

I'm hardly one for suggesting adding another piece of infrastructure to a resource tapped group...but I'd like to hear more from others that are NOT contributing docs about how using an alternative to Confluence may or may NOT sway their decision to participate in the documentation of Sakai.
Sean Keesler
130 Academy Street
Manlius, NY 13104
315-682-0830
sean.keesler@threecanoes.com

On Fri, Oct 1, 2010 at 2:24 PM, Kenneth Robert Romeo <kenro@stanford.edu> wrote:
Ummm ....
Maybe I'll bring up this stupid question again:
It is not my idea, but why aren't we using Sakai for documentation /
communication / etc.?  If it is all that we advertize, then why are we
using Confluence and talking about starting something new on MediaWiki?
At the very least it would reduce the "user experience gap" that Clay
talked about at the conference.
Ken

----Original Message----
From: sakai-user-bounces@collab.sakaiproject.org

[mailto:sakai-user-bounces@collab.sakaiproject.org] On Behalf Of Matt
Clare
Sent: Friday, October 01, 2010 10:44 AM
To: Mathieu Plourde; Sakai User
Cc: sakai2-tcc@collab.sakaiproject.org;
management@collab.sakaiproject.org; Marshall Feldman; Regan, Alan
Subject: Re: [Using Sakai] End-User Documentation

Hi All,

       I thought I'd add some more information about our MediaWiki-based
end-user documentation at Brock University: http://kumu.brocku.ca/sakai

       I am slowly trying to cobble together some information about how
an instruction could re-use our support documentation at
http://kumu.brocku.ca/sakai/Export .  We have also tried to category/tag
everything that references unique Brock content (our SIS, department
names, etc.) and are trying to make adapting our content a
straight-forward process.

       If we are to create central end-user documentation it cannot be in
the current confluence system.  The current confluence site is not at all
end-user friendly; there's too much non-end-user content for browsing or
search to be useful.    I think we need unique articles for each audience
and they should be in their own instances so that the articles are titled
properly and the search is relevant.  What's more is the hyper-linked
nature of a wiki could not be leveraged inside the current confluence
site.  The term "Log-in" and what it means to end-users and administrators
and developers illustrates why they should be separated and are right now.

       I'm keen to share what we have done, but not to invent an audience
for it.  Is that the process we're starting here?  If it is, I'm happy to
contribute content and consensus.

.\.\att

If you're still interested in what we're up to,  read on.....

       I've met with Mathieu about our MediaWiki-based documentation and
he was at my presentation in Denver http://s.mattclare.ca/sakaiwiki    I'm
pleased to see our project so well summarized by him, and as such I have
little to add about the end-user documentation project itself.

       I will say that we choose Mediawiki for a number or reasons, but
what is most relevant to this conversation is the ease at which it can be
updated.  Our documentation is not perfect, but it's a best effort and as
it stands effort is the only thing that keeps it from being perfect.  From
our perspective all the other hurtles of access and other technical
limitations have been removed.

       There is no doubt in my mind that a wiki is the way to go.  In my
opinion our wiki has allowed us to benefit from our local community's
occasional contributions, and allow us to update as needed: sometimes in
the middle of a consultation as the need was identified.

       We choose MediaWiki because of the Wikipedia link and the
PHP/MySQL architecture made it easier to deploy on existing Apache
infrastructure.  The original documentation was scraped from the Sakai
Help tool.  We've used some content from confluence (mostly around
Profile2) but from what I've found in confluence most of the content is
intended for administrators and people like you (reading this E-Mail) not
the typical student or instructor.

       As our support documentation is based on Sakai's own information
it's free for anyone to use, but I think this E-Mail thread has confirmed
that there is no clear path from our customizations back to the broader
community.   This is probably because it's no small task to keep the
information generic enough to apply anywhere.  Generic information tends
to be full of mitigating phrases (If you administrator has....) that
amount to the text being as dense as a legal contract.  To be honest, part
of our customization is to remove these mitigating phrases and simply
state who things work with our Sakai implementation.  But this has already
been identified.  Along side appearance and terminology issues this good
idea remains no small task.

       I'd like to thank everyone who has commented already (especially
Dr. Feldman and Robin Hill).

Cheers,

.\.\att

On 2010-10-01, at 12:04 PM, Mathieu Plourde wrote:

> Hi Sean,
>
> Switching to MediWiki to be the official repository of documentation
would not be more appealing in itself. Confluence is a wiki engine that is
more powerful than MediaWiki, yet also more complicated to use, and not an
obvious choice for academic institutions to adopt. But if we can find a
way to configure an export strategy that could be parsed by multiple
content management engines (wikis are only one category of content
managers) and promote this, that would be great.
>
> Let's say, for instance, that you want to export the content of the
Sakai documentation, but that you call your local instance "Sake", and
that you don't use the Assignments tool. Could there be a way to guide you
through the process of selecting/excluding pages, and doing a bulk find
and replace before exporting? Just a thought.
>
> You're right, we need to find a way to get people to contribute back to
the community documentation. By making the process easy, transparent, and
by applying some quality control mechanisms, we can achieve this, IMO.
>
> Mathieu
>
> On Fri, Oct 1, 2010 at 11:52 AM, Sean Keesler
<sean.keesler@threecanoes.com> wrote:
> Slip of the fingers...I meant confluence, not Jira.
>
> I hear that your requirement is that the "official" community
documentation should be exportable in a format that can be imported into a
free wiki engine. I know that confluence can export spaces into XML docs,
which I imagine could be parsed and imported into other engines (such as
MediaWiki).
>
> Since the community docs are insufficient, the priority for a small
support group is to create their own, rather than contribute to the
community docs. I'm wondering what we could do to reverse the trend; to
make the obvious choice to contribute to the community docs SO THAT they
can use them locally.
>
> To be blunt...would switching to a different wiki (mediawiki) tend to
make the whole thing more appealing? or....is the issue simply that of
resources...as it so often is?
>
>
> Sean Keesler
> 130 Academy Street
> Manlius, NY 13104
> 315-682-0830
> sean.keesler@threecanoes.com
>
>
> On Fri, Oct 1, 2010 at 10:51 AM, Mathieu Plourde <mathieu@udel.edu>
wrote:
> Hi Sean,
>
> MediaWiki is a content management service that makes importing and
exporting very easy. It simply generates an XML containing everything but
the files, which can be exported as a .tar ball.
>
> Using tags (called categories) makes it easy for us to create a workflow
within our own team (which version of Sakai, has the page been revised by
tech writers, which pages require attention now, etc.). Versioning helps
us make decisions on what to keep and throw away.
>
> If Confluence can export in a format that MediaWiki or other free wiki
engines can import, no problem, the documentation can be hosted there.
>
> The current OOTB documentation is so basic (understand incomplete) and
so technical that every institution wants to enhance it with local content
that put it into context. At Delaware, we have separated the help files
(which are tool-centric) from the support documentation (which is oriented
around academic processes). Tagging allows users to forgo the prescribed
information architecture and jump from one context to the other (a user
might see the technical how-to of creating an assignment, switch to a
guide on how to assess student in a relevant way, and then consult a
faculty practice video, for instance).
>
> Mathieu
>
>
> On Fri, Oct 1, 2010 at 10:38 AM, Sean Keesler
<sean.keesler@threecanoes.com> wrote:
> I'm interested in your use of MediaWiki for your docs.
> The ability to start from Brock's existing set of docs seems to make
this appealing....
> Are their other factors that play into that decision? Is it easier to
contribute to a MediaWiki instance than a Jira instance? I'm trying to
figure out if there is an infrastructure recommendation we could make to
the foundation that would help (since you mention that it would be great
if a "a central authority could export the content").
>
> How likely is it that contributing to the community docs in our jira
instance is seen as problematic if there isn't an easy way to repurpose
the content locally?
>
>
>
> Sean Keesler
> 130 Academy Street
> Manlius, NY 13104
> 315-682-0830
> sean.keesler@threecanoes.com
>
>
>
>
> On Fri, Oct 1, 2010 at 9:28 AM, Mathieu Plourde <mathieu@udel.edu>
wrote:
> Hi Alan,
>
> (1) Agreed. One thing we are looking into right now is migrating our
help documentation to MediaWiki, and we'll be starting from Brock
University's instance (https://kumu.brocku.ca/sakai/Main_Page), so that we
don't start from the OOTB documentation of Sakai. If a central authority
could export the content as easily, that would be a clear bonus.
>
> (2) Agreed with making the end-user documentation on top of the page.
Another issue that pops-up from this point is the need to define the
student and instructor role. I wonder if it could be possible to have
drop-down lists at the top of the documentation that would customize the
documentation depending on your role or on the assigned permissions in a
certain tool?
>
> Subscription to a notification service that would push new pages would
also be very nice.
>
> (3) Good user interfaces are usually self-explanatory, but the closer
the hint is to the actual task, the better. Instead of thinking of
"documentation", we should think in terms of "performance support",
providing just enough help, just-in-time. Maybe the contextual help is a
start, but I would like to see more inline ways of getting access to
snippets of information, like access to glossary terms or to the intended
consequences of choosing an option over the other. See Rossett's book on
this topic: http://www.colletandschafer.com/perfsupp/
>
> Mathieu
>
>
> On Thu, Sep 30, 2010 at 3:00 PM, Regan, Alan <Alan.Regan@pepperdine.edu>
wrote:
> Thank you, Michael and everyone.
>
> From our presentation in Denver this summer, we were exploring at a few
areas to address:
>
> (1.) Helping new schools adopt by providing baseline documentation that
could be customized as needed.
>
> (2.) Improving the home page of the Sakai site with official
documentation that is more accessible for faculty or students.
>
> (3.) Revisiting the built-in help pages and considering possible
improvements.
>
> *****
>
> (1.) BASELINE DOCUMENTATION
>
> It takes time to create documentation. Multiply this time across all of
the institutions that use Sakai, and we are duplicating effort again and
again. Could we provide a central repository of documentation, tailored to
the baseline install of Sakai, that a new school could repurpose easily?
Our existing institutions could submit their written work for each tool
and it could be edited into this baseline documentation.
>
> One option would be something like a modified version of IU's custom
documentation solution,
http://ittraining.iu.edu/scripts/oncourse/pdfcreator/  Imagine a school
that's starting fresh checking all the tools they plan to implement and
the service spits out documentation in a desired format, such as RTF,
HTML, or XML so that the adopting school can quickly repurpose.
>
> A pie-in-the-sky solution would be a central wiki service that schools
could subscribe to.  They'd set up a subdomain for their school, select
their version and tools, and it would spit out a complete wiki
documentation site.  They'd modify template colors and images, these
settings would cascade through the wiki site, and they'd be up and running
within moments.  They'd add their editors and could begin replacing text
or screenshots as needed.  This pie-in-the-sky solution could also be a
solution to #2 below.
>
> Challenges: document/style standards, file naming standards, image
screenshot standards, creative commons license, localization, hosting,
administration/management, etc.
>
> (2.) END-USER DOCUMENTATION
>
> The Web site redesign for sakaiproject.org is a great improvement -- it
looks great!  So thanks to everyone who worked on that project.  Here, the
issue is related to the official documentation listed under Support >
Documentation on http://sakaiproject.org.  Dr. Feldman echoes items
mentioned at conferences in Denver and Boston, regarding end-user
documentation.  Look at the "official documentation" links, e.g.
http://confluence.sakaiproject.org/display/DOC/Sakai+2.7  It's too focused
on installation and system administration, ignoring end-users.  The
information here will frighten away instructors and students.
>
> A quick bandaid would be to modify the main documentation page,
http://sakaiproject.org/documentation, and move end-user documentation to
the top, pushing the technical items lower on the page.  Consider renaming
the heading from "Tool demos and tutorials" to "Instructor and student
tutorials and demos" (or similar).  Also, perhaps add a tab to the
official documentation called End-Users or Faculty and Students or
something, and cross-link to an anchor link on the main
sakaiproject.org/documentation page?
>
> Another key item here is peer-to-peer collaboration.  We find that if an
instructor shares an insight ("This works for me and solves problem x")
that other faculty are more likely to listen and try it out.  In addition
to the "how-to" or step-by-step instructions, a mechanism for instructors
to share their best practices within the community would be ideal.  With
Jing and other utilities, many faculty are willing and able to contribute.
Here's an example: "Heard's Hints 1: Entering Text into Courses (Sakai) on
an iPad," http://www.youtube.com/watch?v=U4ewtPPkmJg
>
> NOTE: This summer before the Denver conference, Sean Keesler was already
exploring adding screen capture videos of common Sakai tools to the
documentation area.  I volunteered to capture the Syllabus -- and still
owe him this.  I will work on this next week!
>
> (3.) BUILT-IN HELP
>
> Anecdotally, it's said that users rarely use built-in help.  When they
do, though, it should be easy to use and navigate.  On the whole, I like
the built-in help in Sakai.  I see that many institutions have customized
their built-in help, though.  Can we examine these customizations and
evaluate which changes may inform changes to the built-in help in the
future?  (Page titles, organization, keywords, search, etc.)
>
> *****
>
> Thoughts?
>
> Sincerely,
>
> Alan Regan, MFA
> Manager, Technology and Learning
> Information Technology
> Pepperdine University
> (310) 506-6756
>
>
> ----Original Message----
> From: Michael Feldstein [mailto:michael.feldstein@oracle.com]
> Sent: Wednesday, September 29, 2010 4:27 PM
> To: Robin Hill
> Cc: Sean Keesler; Mathieu Plourde; Marshall Feldman;
sakai-user@collab.sakaiproject.org; Regan, Alan;
sakai2-tcc@collab.sakaiproject.org;management@collab.sakaiproject.org
> Subject: Re: [Using Sakai] End-User Documentation
>
> I'm cross-posting this to the management and Sakai 2 Technical
Coordination Committee lists (the latter of which may bounce, since I
don't think I'm currently signed up for it), mainly because I'm hoping
that the TCC will take this on.
> --
>
>
>
> --
> =================================
>
> Mathieu Plourde, MBA
> Project Leader, LMS/Instructional Designer
> IT-Client Support & Services
> mathieu@udel.edu
> Office: 302-831-4060
>
> =================================
>
> TOP LINKS:
>
> Technology Troubleshooting: http://www.udel.edu/help
> Sakai@UD Support and Training: http://www.udel.edu/sakai/training
>
> =================================
>
>
>
>
> --
> =================================
>
> Mathieu Plourde, MBA
> Project Leader, LMS/Instructional Designer
> IT-Client Support & Services
> mathieu@udel.edu
> Office: 302-831-4060
>
> =================================
>
> TOP LINKS:
>
> Technology Troubleshooting: http://www.udel.edu/help
> Sakai@UD Support and Training: http://www.udel.edu/sakai/training
>
> =================================
>
>
>
>
> --
> =================================
>
> Mathieu Plourde, MBA
> Project Leader, LMS/Instructional Designer
> IT-Client Support & Services
> mathieu@udel.edu
> Office: 302-831-4060
>
> =================================
>
> TOP LINKS:
>
> Technology Troubleshooting: http://www.udel.edu/help
> Sakai@UD Support and Training: http://www.udel.edu/sakai/training
>
> =================================

 ::  Matt Clare
Educational Technology Support Specialist,
Centre for Teaching Learning and Educational Technologies (CTLET)
Part-time Instructor, Interactive Arts and Sciences
Brock University, Niagara Region, Ontario, Canada
www.brocku.ca/ctlet  905 688 5550 xt 4734   Office: SBH315

Isaak/Sakai Question?  http://kumu.brocku.ca/sakai/FAQ

_______________________________________________
sakai-user mailing list
sakai-user@collab.sakaiproject.org
http://collab.sakaiproject.org/mailman/listinfo/sakai-user

TO UNSUBSCRIBE: send email to
sakai-user-unsubscribe@collab.sakaiproject.org with a subject of
"unsubscribe"
_______________________________________________
sakai-user mailing list
sakai-user@collab.sakaiproject.org
http://collab.sakaiproject.org/mailman/listinfo/sakai-user

TO UNSUBSCRIBE: send email to sakai-user-unsubscribe@collab.sakaiproject.org with a subject of "unsubscribe"

_______________________________________________
sakai-user mailing list
sakai-user@collab.sakaiproject.org
http://collab.sakaiproject.org/mailman/listinfo/sakai-user

TO UNSUBSCRIBE: send email to sakai-user-unsubscribe@collab.sakaiproject.org with a subject of "unsubscribe"


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

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

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

TOP LINKS:

Technology Troubleshooting: http://www.udel.edu/help
Sakai@UD Support and Training: http://www.udel.edu/sakai/training

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



Re: [Using Sakai] End-User Documentation
sakai-user-bounces@collab.sakaiproject.org [sakai-user-bounces@collab.sakaiproject.org] on behalf of Robin Hill [Hill@uwyo.edu]
Sent: Wednesday, September 29, 2010 4:24 PM
To: Sean Keesler [sean.keesler@threecanoes.com]; Mathieu Plourde [mathieu@udel.edu]
Cc: Marshall Feldman [marsh@uri.edu]; sakai-user@collab.sakaiproject.org; Regan, Alan [Alan.Regan@pepperdine.edu]
Attachments:
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@uwyo.edu        307-760-8508     http://www/uwyo.edu/ctl\\
________________________________________
From: sakai-user-bounces@collab.sakaiproject.org [sakai-user-bounces@collab.sakaiproject.org] On Behalf Of Sean Keesler [sean.keesler@threecanoes.com]
Sent: Wednesday, September 29, 2010 4:17 PM
To: Mathieu Plourde
Cc: Regan, Alan; sakai-user@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@udel.edu<mathieu@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


Re: Using Sakai End-User Documentation
Marshall Feldman marsh@uri.edu
To help protect your privacy, some content in this message has been blocked. If you are sure that this message is from a trusted sender and you want to re-enable the blocked features, click here.
Sent: | Wednesday, September 29, 2010 1:20 PM
To: | Nicola Monat-Jacobs nicola@longsight.com
Cc: | Robin Hill; sakai-user@collab.sakaiproject.org
Attachments:
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, theR 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.
  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 byDiigo. 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@uwyo.edu 307-760-8508 http://www/uwyo.edu/ctl
________________________________________
From: sakai-user-bounces@collab.sakaiproject.org [sakai-user-bounces@collab.sakaiproject.org] On Behalf Of Marshall Feldman [marsh@uri.edu]
Sent: Wednesday, September 22, 2010 7:41 AM
To: URI Discussions about Sakai; sakai-user@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):

Unknown macro: {Martin Luther King, Jr.}

,

Unknown macro: {race}

, and

Unknown macro: {"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@collab.sakaiproject.org
http://collab.sakaiproject.org/mailman/listinfo/sakai-user\\
TO UNSUBSCRIBE: send email to sakai-user-unsubscribe@collab.sakaiproject.org with a subject of "unsubscribe"


--
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) |

  • No labels