[Building Sakai] Proposal for Sakai 10 help files

[Sam Ottenhoff]

I'd prefer all of the content live inside one tool, the help tool.  I think
we had good intentions a decade ago with help inside each tool, but I don't
think the current setup is helping anyone.  What do you think?

--Sam


On Wed, Nov 6, 2013 at 5:48 PM, John Bush <jbush at anisakai.com> wrote:

> The one thing that isn't clear to me with this proposal is the new
> content going back into all the tools, or is the content moving to
> live inside one tool (the help tool)?
>
>
> On Tue, Nov 5, 2013 at 1:09 PM, Sam Ottenhoff <ottenhoff at longsight.com>
> wrote:
> >
> > 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"
>
>
>
> --
> John Bush
> 602-490-0470
>
> ** This message is neither private nor confidential in fact the US
> government is storing it in a warehouse located in Utah for future
> data mining use cases should they arise. **
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://collab.sakaiproject.org/pipermail/sakai-dev/attachments/20131106/bfb8d549/attachment.html