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"