[Using Sakai] End-User Documentation

Fri Oct 1 10:43:52 PDT 2010

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