[sakai-docs] [Building Sakai] Proposal for Sakai 10 help files

Wed Nov 6 08:19:08 PST 2013

Hi Elizabeth,

I may be able to clarify the question regarding Longsight contributions to
updating the content for Sakai 10.  One of my primary roles at Longsight is
to create a comprehensive set of documentation for Sakai, for both our
clients and the community.  So, yes, we do plan to document all of Sakai
10.  We certainly welcome community help in authoring, since it is a big
job. :-)  However, Longsight is prepared to do the lion's share of the
work.  Also, we don't see this as a one-time deal.  I fully expect to
continue updating the documentation on an ongoing basis as new features are
added or additional use cases evolve.  I'd also love to incorporate links
to community developed resources such as screencasts or videos, like the
ones Adam mentioned.  I see the Sakai help as an ongoing project which will
continue to grow and evolve over time.
Wilma

*Wilma Hodges*
Director of Training & eLearning Initiatives
Longsight
740-599-5005 x812
wilma at longsight.com
www.longsight.com

On Wed, Nov 6, 2013 at 10:49 AM, Venstra, Elizabeth <erytting at iu.edu> wrote:

>  Hi, all—
>
>
>
> For some context, at the last North America Apereo conference, the people
> who turned out to talk about documentation agreed to a two-phase plan—a
> short-term fix to allow people to pitch in to edit the content and write it
> back to trunk, while also developing a list of functional requirements for
> some kind of new help tool in the longer term (Phase 2).  Here is a Google
> doc with discussion around those functional requirements for the new help
> tool:
>
>
>
>
> https://docs.google.com/document/d/1oR6mrE21IkVMgK119ZjLgD9Sn09QUdRJ0Mzi4m7-RKo/edit
>
>
>
> You are all welcome to contribute to this document.  It does already
> contain the idea of allowing local institutions to take the
> canonical/generic help documents, and make local changes without losing the
> benefit of the community work to develop and maintain the canonical
> version.  (By the way, this Google doc is a little messy, but a
> subcommittee including someone from Longsight has been working on creating
> cleaner versions of the requirements in a way that would facilitate
> evaluation of potential tools.)  Since this thread includes the developers’
> list, please note, if you want to contribute to this document, that many of
> the people who originally came together around this need are not
> developers, so the conversation may not be as technical as some of the
> discussion on the developers’ list.  I think it’s very important that
> whatever path the community pursues, there be an easy way for people who
> are in less technical roles—e.g., staff who primarily support faculty, who
> know what the user needs are—to contribute content.
>
>
>
> I take it that Sam’s proposal is for Phase 1, i.e., a short-term fix that
> could be refined or replaced in Phase 2.
>
>
>
> Personally, I don’t really care what tool the community uses; I’m most
> interested simply in seeing some system for editing the content in place as
> soon as possible.  This subcommittee that I mentioned has been testing the
> Drupal solution that Sam set up as the answer to Phase 1, but if this can
> be rolled out as quickly (or maybe even more quickly?), and is easy to use,
> that’s fine with me.
>
>
>
> I’d like to clarify who will do what about the content.  Sam, you said
> that Longsight would be willing to contribute staff to updating the content
> for Sakai 2.10—all the content?  Do you just want to do that yourselves, or
> get the community involved in the process?  What about after 2.10?  Is the
> idea that the responsibility for maintaining the content will revert to the
> community of documentation volunteers after 2.10?  (The idea of having
> Longsight contribute staff to the editing of the content is very
> welcome—better than I expected for Phase 1.)
>
>
>
> Best,
>
>
>
> Elizabeth Venstra
>
> Knowledge Management team
>
> University Information Technology Services
>
> Indiana University
>
> erytting at iu.edu
>
> 812-855-0459
>
>
>
>
>
> *From:* sakai-docs-bounces at collab.sakaiproject.org [mailto:
> sakai-docs-bounces at collab.sakaiproject.org] *On Behalf Of *Adam Marshall
> *Sent:* Wednesday, November 06, 2013 10:01 AM
> *To:* Sam Ottenhoff; Developers Sakai-Dev;
> sakai-docs at collab.sakaiproject.org
> *Subject:* Re: [sakai-docs] [Building Sakai] Proposal for Sakai 10 help
> files
>
>
>
> Improving help would be fantastic, on a scale of 1-10 I’d give it 11.
>
>
>
> This is something really should have happened 5 or 6 years ago - the help
> is sakai is very poor and this idea from Longsight is too good to turn down.
>
>
>
> Rutgers developed screen-shot based help a number of years ago. I wonder
> whether that would be a good starting point? It looks like it could save
> weeks of work eg, http://rci.rutgers.edu/~oirt/sakai/helpdocs2/index.php/
> http://rci.rutgers.edu/~oirt/sakai/helpdocs2/resources.php
>
>
>
> You are very welcome to use any of our Creative Commons tool guides:
> https://weblearn.ox.ac.uk/access/content/group/info/guidance/guides.htmlbut note that there are some Oxford specific features. We also have videos
> which could be embedded.
>
>
>
> What would be brilliant would be if the authoring system allowed different
> views on the document, as an example, we’d use the default help but would
> then create a “patch” which is somehow overlaid onto the base documentation
> which could reflect local changes. We would then export our overlaid
> version. Maybe it does do this, I must confess I haven’t swotted up. If
> not, are there alternatives>
>
>
>
> I think folks on Sakai-user would be interested in this initiative too.
>
>
>
> adam
>
>
>
> *From:* sakai-dev-bounces at collab.sakaiproject.org [
> mailto:sakai-dev-bounces at collab.sakaiproject.org<sakai-dev-bounces at collab.sakaiproject.org>]
> *On Behalf Of *Sam Ottenhoff
> *Sent:* 05 November 2013 20:09
> *To:* Developers Sakai-Dev; sakai-docs at collab.sakaiproject.org
> *Subject:* [Building Sakai] Proposal for Sakai 10 help files
>
>
>
>
>
> *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-docs mailing list
> sakai-docs at collab.sakaiproject.org
> http://collab.sakaiproject.org/mailman/listinfo/sakai-docs
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://collab.sakaiproject.org/pipermail/sakai-docs/attachments/20131106/80b49409/attachment-0001.html 