[Building Sakai] Proposal for Sakai 10 help files

Tue Nov 5 12:31:55 PST 2013

Absolutely needed.  If it´s difficult for the english speaker community
maintain help... for the other languages is a total nightmare.  We need a
new system, don't know if ScreenSteps (seems a good option) or other... but
actual help is not an option.

So +1  or +50 if possible!!!!

2013/11/5 Sam Ottenhoff <ottenhoff at longsight.com>

>
> *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-dev mailing list
> sakai-dev at collab.sakaiproject.org
> http://collab.sakaiproject.org/mailman/listinfo/sakai-dev
>
> TO UNSUBSCRIBE: send email to
> sakai-dev-unsubscribe at collab.sakaiproject.org with a subject of
> "unsubscribe"
>

-- 
***************************************
*Diego del Blanco Orobitg*
Spain & LATAM Regional Manager (*ANI Sakai*)
Apereo LATAM Representative (*Apereo Foundation*)

P: (+34) 653 683 489
E: ddelblanco at anisakai.com
Sk: ddelblanco.ani
***************************************
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://collab.sakaiproject.org/pipermail/sakai-dev/attachments/20131105/6f23cc9e/attachment.html 