[Using Sakai] End-User Documentation

Fri Oct 1 08:52:16 PDT 2010

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

On Fri, Oct 1, 2010 at 10:51 AM, Mathieu Plourde <mathieu at 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 at 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 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/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 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
>>>
>>> =================================
>>>
>>
>>
>
>
> --
> =================================
>
> 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/54912522/attachment.html 