[Building Sakai] Proposal for Sakai 10 help files

[Sam Ottenhoff]

*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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://collab.sakaiproject.org/pipermail/sakai-dev/attachments/20131105/10ed6242/attachment.html 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: sakai-help.PNG
Type: image/png
Size: 85860 bytes
Desc: not available
Url : http://collab.sakaiproject.org/pipermail/sakai-dev/attachments/20131105/10ed6242/attachment.png