[Building Sakai] Proposal for Sakai 10 help files

Wed Nov 6 15:34:22 PST 2013

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