[Building Sakai] [sakai-docs] Proposal for Sakai 10 help files

[Sam Ottenhoff]

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> 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> 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).  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
> http://collab.sakaiproject.org/mailman/listinfo/sakai-docs
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://collab.sakaiproject.org/pipermail/sakai-dev/attachments/20131105/1a30907d/attachment.html