[sakai-docs] Proposal for Sakai 10 help files

Wed Nov 6 02:08:03 PST 2013

The conversation around the KB tool has been going on for sometime. It was waiting on enough interest to generate resources.  I was wondering if the doc community has that interest. Please shout out on this discussion your views. Time to push in the same direction.

Regards,
           Alan

Alan Berg

Innovation working group
On the use of ICT in Education & Research
University of Amsterdam
________________________________
From: sakai-docs-bounces at collab.sakaiproject.org [sakai-docs-bounces at collab.sakaiproject.org] on behalf of Sam Ottenhoff [ottenhoff at longsight.com]
Sent: 05 November 2013 23:16
To: Developers Sakai-Dev; sakai-docs at collab.sakaiproject.org
Subject: Re: [sakai-docs] Proposal for Sakai 10 help files

So there are two topics embedded here: authoring of help content and display of help content.  The advantage of an authoring environment like ScreenSteps is that it provides collaborative editing, easy-to-use image annotation tools, nice export possibilities, and we can start using it today.  For display of help content, Sakai's existing help system handles multiple languages already.  I don't think we could internationalize the Edia KB tool and make it export in time for Sakai 10 without significant commitments from other SCAs and institutions.

--Sam

On Tue, Nov 5, 2013 at 4:48 PM, Jaeques Koeman <jaeques at edia.nl<mailto:jaeques at edia.nl>> wrote:
If neither the current solution (current help), the proposed solution (screensteps) and the alternative solution (Edia Sakai KB) are fully multi-lingual, why don't you consider to make the latter fully multi-lingual? After all, it is fully role, permission and site aware.

To me it seems that the efforts required to make this tool work for everyone are similar or less than the proposed commercial path.

Here is the link to the presentation that Neal Caidin, Alan Berg and myself gave at the last conference.

http://www.slideshare.net/jaeques/knowledge-base-online-help

Rgds, Jaeques

Op 5 nov. 2013 om 21:09 heeft Sam Ottenhoff <ottenhoff at longsight.com<mailto:ottenhoff at longsight.com>> het volgende geschreven:

Proposal: For Sakai 10, we should replace much of our help content with role-focused, image-heavy content.  Our existing help content displays the same content for instructors and students and includes few images.  I propose that we delete the existing help files that are contained within the individual Sakai tools, author new content in a documentation-friendly system, and export that image-heavy new content into Sakai's existing help tool.

Proposal for Authoring: I propose that Apereo pay for a community account in the commercial system called ScreenSteps Live (http://www.screensteps.com/).  ScreenSteps would allow ten of our trusted community members to collaborate and edit documents in the shared system for $99/month.  ScreenSteps would be used as a collaborative editing system; the content would be exported and held within Sakai's existing SVN repository.

Why ScreenSteps and not a basic HTML editing system?  These are the primary reasons I can find:

a) ScreenSteps makes adding and annotating images incredibly easy.

b) ScreenSteps allows exports into PDF guides and HTML (that we would use to import into Sakai's existing help system).

c) ScreenSteps could allow institutions to easily export into an existing campus system like Wordpress or ZenDesk.

d) Institutions that want to heavily customize their own help could pay for their own ScreenSteps account.

Proposal for Sakai changes: I believe the changes in Sakai would be relatively minor.  Here are the changes I would look to make:

a) Delete all existing help files in individual tools.

b) Develop a script that could easily import a ScreenSteps HTML ZIP export into appropriate help directories.

c) Add functionality to help tool that will differentiate content based on role (Student vs Instructor/teacher vs learner)

If there are other developers interested in re-doing help, we could consider replacing the existing help with a simplified version that depended on simple HTML files, ElasticSearch (already in for Sakai 10), and a more streamlined appearance.

Who is going to edit this new content? Longsight has staff dedicated to rewriting help files between now and Sakai 10's release.  We also believe there are existing community members who are eager to work on restructured help files.

What about multi-lingual content? Sakai's existing help tool supports multi-lingual content.  ScreenSteps allows multiple sets of content to be created, or the static HTML could be translated manually or using a tool like Crowdin.

How is the content licensed?  The content would be exported and licensed as ECL 2.0 content held within our SVN repository.  Contributors to the collaborative editing should sign CLAs similarly to developers.

What if ScreenSteps goes away? Then we are in the same boat we are in now.  We would need a new system for collaboratively editing HTML-based help documents besides manually editing HTML inside an SVN repository.  If we consolidate help files and remove them from within each individual tool, this should become much easier.

Other possibilities that have been discussed: The Edia Knowledgebase tool would be a nice replacement for the existing help tool, but it does not currently support multilingual content like our existing help tool.  I also built a Drupal-based proof of concept for editing existing help files (http://sakaihelp.longsight.com<http://sakaihelp.longsight.com/>).  I view ScreenSteps as a refined version of that POC that has much better image editing capabilities and much better export possibilities.  Also, a ScreenSteps account should be controlled by the Sakai community where the Drupal-based proof of concept is tied to Longsight.

Attached: a screenshot of a quick POC of ScreenSteps-exported content using the existing Sakai help tool.

Sample of a ScreenSteps guide used by Canvas: http://guides.instructure.com/m/8470

Canvas has a document about how to contribute to their ScreenSteps documentation: http://guides.instructure.com/s/2204/m/4151/l/41924-how-do-i-contribute-my-training-materials-to-canvas-guides

Thoughts, comments, or realistic alternatives for Sakai 10 help files?  If I hear no objections, I'd like to get started on some of the technical work in early December.

--Sam
<sakai-help.PNG>
_______________________________________________
sakai-docs mailing list
sakai-docs at collab.sakaiproject.org<mailto:sakai-docs at collab.sakaiproject.org>
http://collab.sakaiproject.org/mailman/listinfo/sakai-docs

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://collab.sakaiproject.org/pipermail/sakai-docs/attachments/20131106/fe72be5a/attachment.html 