[Sugar-devel] [DESIGN RFC] Onboarding

[Tony Anderson]

Hi, Sam

What is our contextual help system?  Do you mean right-click popups?

Your proposal mentions the need for a simple trigger. The help button 
(or a sub-option) should invoke the class specifying a particular 
onboard 'tutorial'.
For Python that seems very straightforward.

Yes,  there is the initial 'onboarding' prerequisite that enables the 
user to use your onboarding: opening the laptop, powering up, hitting 
keyboard keys with the end of the fingers (knuckles bent), knowing where 
the trackpad and mouse keys are, knowing that moving one's finger on the 
trackpad moves a cursor, what is a cursor and so on).  I have seen XOs 
in schools where the participants have never even seen a light-switch. 
So yes, they would also need to know how to click on a help button to 
start an 'onboarding' tutorial. However, once that is understood, it 
becomes easy to build tutorials using the same underlying software so 
that deployments and community members can help.

Onboarding for an editor involves knowing how to open a new document or 
restore an existing one. Once some text is available for editing, 
knowing how to set the focus by moving the cursor, knowing how to insert 
and delete text. Many beginners have trouble knowing that the computer 
performs editing actions untile the enter key is pressed.

If you provide a python implementation with methods, then json or some 
other technique could be used to invoke those methods. It might be 
useful to look
at your scenarios and how they might be described as data:

{'hotspot':'Record.activity','popup':'recordpopup.png','click':'Record.activity', 
'expect':'recordmainpage.png'}

Whether you use json is immaterial. However, an approach going through 
your scenarios in some pseudocode (imaginig you are developing an 
interpreter) can help you imagine what methods will be needed, what will 
need to be shown on popups, and how you will be able to test for completion.

Tony

On 12/30/2015 12:42 PM, Sam P. wrote:
> Hi Tony,
>
> Thank you for the comments on the proposal.
>
> (For context, by onboarding I refer to the users first run 
> experience.  Similar to [1].  Specifically something that helps them 
> understand the basics of sugar)
>
> From an implementation perspective it is important as you note to bind 
> to widgets rather than hard coded positions and recognise when the 
> user completes the task.  I think from that perspective, it would be 
> very complex to use a JSON file.  I would much prefer to have a 
> singleton class "Onboarder" (or whatever) which would have 2 main 
> methods.  "add_hotspot_over(hotspot, widget)" and simmilar for other 
> places that hotspots are placed over and 
> "signal_hotspot_completed(hotspot)" which signals that a hotspot has 
> been completed.  There would then be a separate list of hotspots and 
> their content.  Having more of the implementation in python in will 
> give this flexability.
>
> I feel that adding lots of different tutorial in different places 
> almost conflicts with our contextual help system (the help window that 
> pops up).  I think that adding a small initial explanation/tutorial is 
> a different issue and targets a different need.  Does this need to be 
> added to the onboarding though (how to open the help)?
>
> Supporting the F6 frame activation could be added, I will mock 
> something up tomorrow.
>
> Earlier you mentioned that design should use more icons than text.  I 
> think that I could show screen shots of the expected result.  However, 
> sometimes I personally find icons can be more vauge than text for 
> explaining ideas, and I believe that some users may feel a similar 
> way.  Therefore I believe that the supplementary copy could be helpful 
> for many users.  However, I you point out the issue of translation 
> loads.  Should the copy be hidden if text is not available in the same 
> language?
>
> Thanks,
> Sam
>
> [1] https://useronboard.com
>
> On Wed, Dec 30, 2015 at 6:24 PM, Tony Anderson <tony_anderson at usa.net 
> <mailto:tony_anderson at usa.net>> wrote:
>
>     Some thoughts:
>
>         Trigger this with the help button (see TurtleBlocks). If there
>     is already a help, make the help button show options:
>             help
>             tutorial: how to launch an activity
>
>     where tutorial is the Onboarding implementation. It should be
>     possible to have more than one tutorial with some description of
>     the purpose.
>
>     Add a help button to the left of the home view button on the home
>     view and the list view (list view help gives tutorial on list view.
>     Add a help button to the right upper corner of the frame.
>     Add a help button on the bottom bar of the Journal view (away from
>     the mount icons but not in the far corner to avoid conflict with
>     the frame)
>     Add a help button on the top bar of the neighborhood and group
>     views (to the right, away from the corner)
>
>     Implement the system so that activity author/maintainers can
>     create their own help button tutorials.
>
>     Use a list of jsons to define the steps in the tutorial:
>         [{'hotspot':'x,y,w,h','click':test for completion,....}
>
>     On the home view, at the deployments I support, pressing the alt
>     key makes 'always start new' the default. This makes it easier to
>     separate a
>     deliberate attempt to resume a task (from the Journal) from a new
>     task (from the Home view). With the above approach, the home view
>     tutorial can be
>     easily modified.
>
>     For the frame, the corners are disabled so that the frame is only
>     available from the frame key. This is essential for the original
>     XO-1 keyboard since moving the cursor to stop an activity almost
>     invariably covers the button with the frame. It would be nice if
>     the tutorial implementation had a way to show a keyboard hotspot
>     (e.g. a on-screen keyboard) to show how to access various views
>     from the keyboard.
>
>     In the context of the proposal:
>
>         Onboarding goals should be supported by the implementation but
>     not limited.
>
>         User flow: user clicks on help button and clicks on tutorial
>     (if more than one option).
>                         home view tutorial shows how to launch an
>     activity - but an activity has it's own help button and tutorial
>
>     When a user completes an onboarding task, the window should flash
>     through a huge tick, then fade away.
>                         a new hotspot appears to set up the next task.
>
>     The image in the popup could be a screen shot showing the expected
>     result of the previous task.
>
>     So, in general, the tutorial definition should be separated from
>     the tutorial mechanism.
>
>     I suspect the 'hotspot' implementation to be relatively easy but
>     the tricky code will be to determine whether the task was executed
>     correctly.
>
>     The hotspot mechanism must be able to handle changes. Suppose that
>     a home view tutorial sets a task to launch 'Record' by placing a
>     hotspot around the Record icon. The mechanism needs to find where
>     the Record icon is on the home view, not just position it where
>     Record shows in a
>     freshly-installed Home View. The user (or deployment) could have
>     added or removed activities from favorites.
>
>     Tony
>
>     On 12/29/2015 03:55 AM, Tony Anderson wrote:
>
>          The important thing is Sam's proposal and its implementation.
>
>         Two considerations:
>
>              1) Make the implementation scriptable as much as possible
>         so that new help scenarios can be easily implemented in the wild.
>              2) Minimize text - emphasize icons. For example, a
>         standard 'click' icon. This reduces the stress of making
>         translations.
>
>         Tony
>
>
>     _______________________________________________
>     Sugar-devel mailing list
>     Sugar-devel at lists.sugarlabs.org
>     <mailto:Sugar-devel at lists.sugarlabs.org>
>     http://lists.sugarlabs.org/listinfo/sugar-devel
>
>
>
>
> _______________________________________________
> Sugar-devel mailing list
> Sugar-devel at lists.sugarlabs.org
> http://lists.sugarlabs.org/listinfo/sugar-devel

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.sugarlabs.org/archive/sugar-devel/attachments/20151230/00ea263b/attachment-0001.html>