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

Wed Nov 6 12:34:12 PST 2013

My sense (or bias) as a documentation editor is that yes, screenshots are more expensive than text; they are often more likely to need to be redone, and typically at least a little more trouble to redo than simply editing the text.  Video, even more so.  Therefore, they should not be used everywhere.  There's a sliding scale of added value, from the icon that has no name in the UI (including an image is the only thing that tells the user what icon you're talking about), through the screenshot with an arrow added on top showing something that's otherwise hard to find, down to the screenshot of a button that says "Submit" (which adds nothing to the simple text "Click Submit").  But it will be up to the documentation editors to find the balance point, and if Longsight is planning on sticking with the documentation effort for the long haul, they will likely find that balance point pretty quickly based on their available time.

All of that applies to the UI generally, but as far as the skin, it is possible to create screenshots and/or videos that focus on the Sakai tools themselves, for greater portability across institutions.  Our IT Training unit here at Indiana does their video tutorials that way (although the part about sharing them with the Sakai community never came to fruition).  They are arguably a bit less useful than if they showed the whole screen, but still somewhat useful.  Here's an example; see what you think.

http://www.iu.edu/~ittrain/oncourse/feature_demos/forums_grade/multiscreen.html

best,

Elizabeth Venstra
Knowledge Management team
University Information Technology Services
Indiana University
erytting at iu.edu<mailto:erytting at iu.edu>
812-855-0459

From: Steve Swinsburg [mailto:steve.swinsburg at gmail.com]
Sent: Wednesday, November 06, 2013 2:58 PM
To: Margaret Wagner
Cc: sakai-dev; Venstra, Elizabeth; sakai-docs at collab.sakaiproject.org; Sam Ottenhoff
Subject: Re: [Building Sakai] Proposal for Sakai 10 help files

I like the idea of improving help. My only obvious concern is that screenshots are no doubt going to be taken of a base Sakai skin, but for those that customise the skin a lot, it won't match up to their own system.

At various places I've worked in the past they created tutorials like these but they were out of date when the skin was updated and the time and effort to redo them was prohibitive.

Just something for discussion.

Cheers
Steve

sent from mobile device
On 07/11/2013 6:22 AM, "Margaret Wagner" <mwagner at umich.edu<mailto:mwagner at umich.edu>> wrote:

A few things that we might want to consider (some may have been mentioned):

1.  Accessibility of the content created with ScreenSteps.

2.  Many websites provide several types of help to meet diverse user preferences.  Some people don't want to watch videos.  Others don't want to wade through lots of images to find simple steps they can read.  Still others really need images to get anywhere.

A site may include some combination of the following...

---- Detailed instructions with detailed images for getting started

---- Short getting started cheat sheet

---- A video tutorial covering the basics

---- Interactive e-learning tutorial

---- Manual for the basics

---- Manual for advanced features

---- Very quick how-to step-by-steps of some tasks with no images

---- Forums for finding best practices and asking questions

... plus other types of help

We've recently added links to videos and embedded videos in our help pages.  We've also included links to printable pdfs.  (We use our own content pages with the Sakai/CTools help tool.)

3.  Knowledge bases that can really zero in on a topic are best.  Out of curiosity I typed "getting started" in the TurboTax knowledge base search and I got over 13,000 hits.  I stopped searching for basic instructions on getting started after page 4.

On Wed, Nov 6, 2013 at 2:09 PM, Sam Ottenhoff <ottenhoff at longsight.com<mailto:ottenhoff at longsight.com>> wrote:

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:

Hi Elizabeth,

So what is the plan of documentation group with Phase 2 and the implementation of these requirements?  Is there a plan to raise money, request bids, and contract for development to meet the requirements?  If yes, is there any progress or an ETA to share?

To your question about the limit on the number of contributors: ScreenSteps allows for 20 contributors for twice the price.  If we suffer a deluge of active contributors, by all means, let's go for the higher subscription level.

--Sam

_______________________________________________
sakai-dev mailing list
sakai-dev at collab.sakaiproject.org<mailto: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<mailto:sakai-dev-unsubscribe at collab.sakaiproject.org> with a subject of "unsubscribe"

_______________________________________________
sakai-dev mailing list
sakai-dev at collab.sakaiproject.org<mailto: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<mailto: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-docs/attachments/20131106/065f1267/attachment.html 