[Using Sakai] End-User Documentation

Fri Oct 1 07:38:11 PDT 2010

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 at threecanoes.com

On Fri, Oct 1, 2010 at 9:28 AM, Mathieu Plourde <mathieu at 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 at 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/documentationpage?
>>
>> 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 at oracle.com]
>> Sent: Wednesday, September 29, 2010 4:27 PM
>> To: Robin Hill
>> Cc: Sean Keesler; Mathieu Plourde; Marshall Feldman;
>> sakai-user at collab.sakaiproject.org; Regan, Alan;
>> sakai2-tcc at collab.sakaiproject.org; management at 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 at udel.edu
> Office: 302-831-4060
>
> =================================
>
> TOP LINKS:
>
> Technology Troubleshooting: http://www.udel.edu/help
> Sakai at UD Support and Training: http://www.udel.edu/sakai/training
>
> =================================
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://collab.sakaiproject.org/pipermail/sakai-user/attachments/20101001/4bd68d4d/attachment.html 