[Building Sakai] Proposal for Sakai 10 help files

Wed Nov 6 15:22:38 PST 2013

Yea, a lot of the big schools that customize it do this and don't even use
the internal help. This is one of the reasons it hasn't gotten a lot of
internal attention. As long as the context sensitive "?" links can work,
which all it does is pass the tool id as a parameter, so I'm sure it could
be a simple proxy that redirects to something, then nobody knows what
you're using.

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

> Yes exactly!  It's much like i18n the people that end up doing it are
> the same people and having it one place makes much sense.  Also, it
> would make it easier for institutions who wish to change it to manage
> it.  Also, makes it easier to have it on a separate update schedule
> that the rest of the app, or maybe even live outside of Sakai
> altogether.
>
> FYI, for those who don't know, the existing help tool does let you
> host the help on a separate server and manage things in one app
> already.  That is how we do it.  You just have to provide the help.xml
> manifest to categorize and index the content.
>
> On Wed, Nov 6, 2013 at 4:06 PM, Sam Ottenhoff <ottenhoff at longsight.com>
> wrote:
> > 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. **
> >
> >
>
>
>
> --
> 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. **
> _______________________________________________
> 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"
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://collab.sakaiproject.org/pipermail/sakai-dev/attachments/20131106/a071533d/attachment.html 