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

Wed Nov 6 11:01:23 PST 2013

Great news!

One more question upon glancing over Sam's proposal again.  There would be a maximum of 10 editors, I see.  That's including both Longsight's staff and community volunteers?  Assuming that's true, how many volunteers would there be room for?

If there were to be meaningful community engagement in the process, I would have hoped for a slightly larger number of people participating.  If it's a volunteer effort, one would want a number of people to share the work, although obviously, the group could get too big.  However, I don't think a substantial level of volunteer community engagement would be better than Longsight doing all the work, or all but whatever share a very small number of volunteers could contribute.  The prospect of getting volunteers to do work on a project like this is always chancy, and the job would undoubtedly be more complete, thorough, and consistent if Longsight did all or most of it.  So, while I think the ideal might be for Longsight to do the lion's share alongside a few more volunteers than 10-x (whatever x is), that's not a reason not to go with this proposal, in my view.

Elizabeth

From: Wilma Hodges [mailto:wilma at longsight.com]
Sent: Wednesday, November 06, 2013 11:19 AM
To: Venstra, Elizabeth
Cc: Adam Marshall; Sam Ottenhoff; Developers Sakai-Dev; sakai-docs at collab.sakaiproject.org
Subject: Re: [sakai-docs] [Building Sakai] Proposal for Sakai 10 help files

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<mailto:wilma at longsight.com>
www.longsight.com<http://www.longsight.com>

On Wed, Nov 6, 2013 at 10:49 AM, Venstra, Elizabeth <erytting at iu.edu<mailto: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<mailto:erytting at iu.edu>
812-855-0459<tel:812-855-0459>

From: sakai-docs-bounces at collab.sakaiproject.org<mailto:sakai-docs-bounces at collab.sakaiproject.org> [mailto: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<mailto: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.html but 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> [mailto: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<mailto: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<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<mailto: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/760711c4/attachment-0001.html 