[Building Sakai] Proposal for Sakai 10 help files

Fri Nov 8 14:27:46 PST 2013

Does anyone else have thoughts on content management and collaboration
around Sakai help file authoring?

Neal, can you begin pursuing Apereo funding and control of an account with
ScreenSteps?

--Sam

On Wed, Nov 6, 2013 at 6:34 PM, Aaron Zeckoski <azeckoski at unicon.net> wrote:

> Having i18n files distributed out into plugins/blocks/modules/etc. is
> pretty common in a lot of large pluggable open source projects.
>
> Example: http://codex.wordpress.org/Writing_a_Plugin
> In this example all the core i18n is located in a central location
> (for wordpress core) because they use gettext which extracts all the
> strings into a single file (just because that is how it works so that
> is intrinsic to use of gettext more than anything else).
>
> -AZ
>
>
> On Wed, Nov 6, 2013 at 6:20 PM, Matthew Jones <matthew at longsight.com>
> wrote:
> > I think the only advantage of the way the current system works is that it
> > allowed help files for contrib tools to drop in easier as you added them.
> >
> > Though if we had these contrib tools contribute to the central help file
> > that would be just the same thing. Ideally the local system would filter
> > content based on what tools you had available, but I think that's the
> only
> > real requirement. I think it would work just as well and be easier to
> manage
> > all in one place.
> >
> > Having all the translation files scattered also had this advantage, but
> had
> > the disadvantage of needing to update 50 tools when you want to update
> > translations. This differs from some other systems that have all of their
> > strings and locales for everything in one big file in central location. I
> > think we've found having all of the strings in one place (like the
> database)
> > makes things easier, so having all of the help files will too.
> >
> > I think it would be nice if it could still work with that old system,
> but I
> > wouldn't make it a blocker.
> >
> > 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. **
> >> _______________________________________________
> >> 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"
> >
> >
> >
> > _______________________________________________
> > 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"
>
>
>
> --
> Aaron Zeckoski - Software Architect - http://tinyurl.com/azprofile
> _______________________________________________
> 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/20131108/6ffa0bc3/attachment.html 