[Using Sakai] End-User Documentation

Thu Oct 7 08:57:34 PDT 2010

Hi Sean and cross-posted list people,

I created a page to brainstorm about end-user documentation, and try to
gauge the interest of Sakai colleagues. See
http://confluence.sakaiproject.org/display/ESUP/Help+Files+and+Documentation+Process+Redesign

Mathieu

On Fri, Oct 1, 2010 at 3:59 PM, Sean Keesler
<sean.keesler at 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 at threecanoes.com
>
>
>
> On Fri, Oct 1, 2010 at 2:24 PM, Kenneth Robert Romeo <kenro at 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 at collab.sakaiproject.org
>> [mailto:sakai-user-bounces at collab.sakaiproject.org] On Behalf Of Matt
>> Clare
>> Sent: Friday, October 01, 2010 10:44 AM
>> To: Mathieu Plourde; Sakai User
>> Cc: sakai2-tcc at collab.sakaiproject.org;
>> management at 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 at 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 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
>> >
>> > =================================
>> >
>> >
>> >
>> >
>> > --
>> > =================================
>> >
>> > 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
>> >
>> > =================================
>>
>>  ::  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 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
>
> TO UNSUBSCRIBE: send email to
> 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
Office: 302-831-4060

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