[Building Sakai] Proposal for Sakai 10 help files

Tue Nov 12 05:13:42 PST 2013

Hi Sam,

I'm looking into Apereo funding for a Screensteps account at the 10 author
level for non-profits. I'll keep you posted.

Cheers,
Neal

On Fri, Nov 8, 2013 at 5:27 PM, Sam Ottenhoff <ottenhoff at longsight.com>wrote:

> 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"
>>
>
>
> _______________________________________________
> 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/20131112/4ce2617d/attachment.html 