[Using Sakai] End-User Documentation
Sean Keesler
sean.keesler at threecanoes.com
Fri Oct 1 12:59:11 PDT 2010
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"
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://collab.sakaiproject.org/pipermail/sakai-user/attachments/20101001/ac42f5dc/attachment-0001.html
More information about the sakai-user
mailing list