Difference between revisions of "Features/Introduction Tutorial"

From Sugar Labs
Jump to navigation Jump to search
(→‎Documentation: tutorius.org is got grabbed :-/)
 
(24 intermediate revisions by one other user not shown)
Line 19: Line 19:
  
 
== Current status ==
 
== Current status ==
* Targeted release: 0.90
+
* Targeted release: Undefined
* Last updated: 03-13-2010
+
* Last updated: 04-26-2010
* Percentage of completion: 10%
+
* Percentage of completion: Suspended
 +
 
 +
Note: Due to a higher than expected work requirement at the master level, I'll be suspending work on Tutorius indefinitely.  I'll leave the page here, so that the idea is still available.  Should anybody want to have more information on how Tutorius was working, I'll be glad to share.
  
 
== Detailed Description ==
 
== Detailed Description ==
Line 28: Line 30:
 
The proposal aims at giving an overview of the Frame, the different Views, the Journal, Browse and Write in a single tutorial.  
 
The proposal aims at giving an overview of the Frame, the different Views, the Journal, Browse and Write in a single tutorial.  
  
The tutorial should be stored in the user home directory, alongside any activity data, as an XML file representing the execution states of the tutorial.
+
The tutorial should be stored as an XML file representing the execution states of the tutorial.
  
 
Translation of the tutorial should be made using the gettext convention by storing translations of the tutorial strings along side the XML file using the gettext schema (.po, .pot, .mo files).
 
Translation of the tutorial should be made using the gettext convention by storing translations of the tutorial strings along side the XML file using the gettext schema (.po, .pot, .mo files).
Line 39: Line 41:
 
This feature should lower the barrier of entry to Sugar by making it easier to learn the platform by having to resort less to external documentation.
 
This feature should lower the barrier of entry to Sugar by making it easier to learn the platform by having to resort less to external documentation.
  
As discussed with Gerald Ardito, picking up Activities seems to work well for most students. However, getting used to the specific idioms of Sugar requires more efforts.
+
As discussed with Gerald Ardito, picking up Activities seems to work well for most students. However, getting used to the specific idioms of Sugar requires more efforts and therefore would benefit from having an interactive tutorial.
  
 
== Scope ==
 
== Scope ==
''What work do the developers have to accomplish to complete the feature in time for release? Is it a large change affecting many parts of the distribution or is it a very isolated change? What are those changes?''
+
Most of the work has already been done as part of the Tutorius project that ended on December 2009. However, there is still some work to do before the existing system can reliably be integrated to Sugar.  The modifications to Sugar as well as the work to be done is outlined below.
 +
 
 +
=== Sugar Modifications ===
 +
The major changes to Sugar consist in introducing two new concepts, Probes and Overlays, and an additional service in the sugar-session.  
 +
 
 +
Probes allow obtaining events from Activities/Shell and the execution of arbitrary actions from a separate process. This ability should be reviewed in light of the security policy of Sugar. 
 +
 
 +
Overlays are Layouts or Windows used to draw custom graphics on top of Activities, the Frame, the Journal or any Sugar View. A more complete description for Probes and Overlays is given in the Tutorius Architecture document referred in the Documentation section.
 +
 
 +
The tutorius service in the sugar-session adds an Engine to execute tutorials, a registering mecanism to register and unregister Probes when Activities are started and stopped and a dbus interface to start and stop tutorials.
 +
 
 +
Those changes involve modifications of less than 100 lines of code in the existing Sugar code base to the following files:
 +
* sugar:bin/sugar-session (Add the tutorius service)
 +
* sugar:src/jarabe/frame/frame.py (Add an Overlay and a Probe)
 +
* sugar:src/journal/journalactivity.py (Add a Probe)
 +
* sugar-toolkit:src/sugar/activity/activity.py (Add a Probe)
 +
* sugar-toolkit:src/sugar/graphics/window.py (Add an Overlay)
 +
 
 +
In addition to the previous modifications:
 +
* The tutorius files should be found under the sugar.tutorius module.
 +
* Some icons will be added. 
 +
* The tutorial will be stored under ./sugar/default/tutorius in the user home directory.
  
 +
=== Tasks ===
 +
# Define an [[Features/Introduction_Tutorial/Script | exact script]] for the introduction tutorial
 +
# Rebase the existing Tutorius code base on top of Sugar 0.88
 +
# Create a reliable [[Features/Introduction_Tutorial/Overlay | Overlay]] for all the different Views and the Frame
 +
# Make the Message Bubble position relative to the screen size
 +
# Make sure the current localization mecanism is reliable
 +
# Add the logging screen option (See UI Mocks)
 +
# Add the option item to replay the introduction tutorial (See UI Mocks)
 +
# Produce a tutorial
 +
# Translate the tutorial in French
 +
# Write documentation for the translation team
  
 +
The only risky item is the creation of a reliable Overlay for the different Views. For a technical description of what it involves, see [[Features/Introduction_Tutorial/Overlay]]. Any help from GTK gurus in the community is welcome, as our last attempt at this was unsuccessful.
  
 
==UI Design==
 
==UI Design==
''Does the feature have a direct impact on the work flow, or does it need a UI? Link here mockups, or add detailed descriptions.''
 
 
This tutorial should be accessible from the first login screen, right after the color selection, and from the option menu:
 
This tutorial should be accessible from the first login screen, right after the color selection, and from the option menu:
  
Line 60: Line 94:
 
http://tutorius.org/blog/wp-content/uploads/2010/03/write-300x216.png
 
http://tutorius.org/blog/wp-content/uploads/2010/03/write-300x216.png
  
The information presented to the user will be essentially composed of bubble messages pointing at screen elements. Progress through the tutorial will be accomplished by the user clicking a next button at the bottom of the screen. Once the tutorial is over, the user will be brought back to the Desktop screen where she will be able to resume interacting with the system normally. At any time during the tutorial, the user can press the Stop button to interrupt the current tutorial an return to the original place where she was at first.
+
The information presented to the user will be essentially composed of bubble messages pointing at screen elements. Progress through the tutorial will be accomplished by the user clicking a next button at the bottom of the screen. Once the tutorial is over, the user will be brought back to the Desktop screen where she will be able to resume interacting with the system normally. At any time during the tutorial, the user can press the Stop button to interrupt the current tutorial and return to the place she was when she started the tutorial.
 
 
  
 
== How To Test ==
 
== How To Test ==
Line 68: Line 101:
  
 
== User Experience ==
 
== User Experience ==
The tutorial won't affect the regular workflow or experience for the platform.
+
The tutorial won't affect the regular workflow or experience for the platform other than providing a tutorial on the first connexion.
  
 
== Dependencies ==
 
== Dependencies ==
Line 80: Line 113:
 
*http://docs.google.com/Doc?docid=0AVT_nzmWT2B2ZGN3dDd2MzRfNTBka3J4bW1kaA&hl=en (Tutorius Engine States)
 
*http://docs.google.com/Doc?docid=0AVT_nzmWT2B2ZGN3dDd2MzRfNTBka3J4bW1kaA&hl=en (Tutorius Engine States)
  
The following document provides a high-level view of the Tutorius Architecture.  The original system was more powerful since it allowed Creation and Sharing of tutorials from within Sugar also.  However, for the purpose of this feature proposal and to ease integration, only the Execution of tutorials will be considered.  For the time being, any reference to the Store, the Workshop, the Creator and the Remote may safely be ignored.  They will be kept in case a further integration of those tools might be envisoned in the future.  
+
The following document provides a high-level view of the Tutorius Architecture.  The original system was more powerful since it allowed Creation and Sharing of tutorials from within Sugar also.  However, for the purpose of this feature proposal and to ease integration, only the Execution of tutorials will be considered.  For the time being, any reference to the Store, the Workshop, the Creator and the Remote may safely be ignored.  They are kept in case a further integration of those tools is accepted by the community in a later release.
*http://docs.google.com/Doc?docid=0ARkLUElWcqxDZGdkOWo3c2ZfOWdqeGtyZmY2&hl=en (Tutorius Architecture)
+
 
 +
The execution scenarios presented are not completely up-to-date and will be revised in the next weeks.  For the time being, the most interesting part should be the component diagrams and descriptions.  
 +
*http://docs.google.com/Doc?docid=0ARkLUElWcqxDZGdkOWo3c2ZfOWdqeGtyZmY2&hl=en#Components_2405436521573161_98 (Tutorius Architecture)
 +
 
 +
* <nowiki>http://www.tutorius.org</nowiki> (Website for the project that ended on December 2009; now owned by a domain grabber)
 +
 
 +
== Source Code ==
 +
 
 +
* http://git.sugarlabs.org/projects/tutorius
  
* http://www.tutorius.org (Website for the project that ended on December 2009)
+
Forks of sugar components:
 +
* http://git.sugarlabs.org/projects/sugar-toolkit/repos/sugar-toolkit-tutorius
 +
* http://git.sugarlabs.org/projects/sugar/repos/tutorius
 +
* http://git.sugarlabs.org/projects/sugar-jhbuild/repos/tutorius
  
 
== Release Notes ==
 
== Release Notes ==

Latest revision as of 12:42, 6 March 2012



Summary

Provide an interactive introduction to Sugar for first-time users.

Owner

Current status

  • Targeted release: Undefined
  • Last updated: 04-26-2010
  • Percentage of completion: Suspended

Note: Due to a higher than expected work requirement at the master level, I'll be suspending work on Tutorius indefinitely. I'll leave the page here, so that the idea is still available. Should anybody want to have more information on how Tutorius was working, I'll be glad to share.

Detailed Description

The proposal consists in providing a default interactive tutorial for Sugar that will give an overview of the particularities of the Sugar interface.

The proposal aims at giving an overview of the Frame, the different Views, the Journal, Browse and Write in a single tutorial.

The tutorial should be stored as an XML file representing the execution states of the tutorial.

Translation of the tutorial should be made using the gettext convention by storing translations of the tutorial strings along side the XML file using the gettext schema (.po, .pot, .mo files).

The tutorial should be independent of the screen resolution.

For the 0.90 release, the tutorial won't be user modifiable other than by modifying the XML format by hand, which won't be recommended.

Benefit to Sugar

This feature should lower the barrier of entry to Sugar by making it easier to learn the platform by having to resort less to external documentation.

As discussed with Gerald Ardito, picking up Activities seems to work well for most students. However, getting used to the specific idioms of Sugar requires more efforts and therefore would benefit from having an interactive tutorial.

Scope

Most of the work has already been done as part of the Tutorius project that ended on December 2009. However, there is still some work to do before the existing system can reliably be integrated to Sugar. The modifications to Sugar as well as the work to be done is outlined below.

Sugar Modifications

The major changes to Sugar consist in introducing two new concepts, Probes and Overlays, and an additional service in the sugar-session.

Probes allow obtaining events from Activities/Shell and the execution of arbitrary actions from a separate process. This ability should be reviewed in light of the security policy of Sugar.

Overlays are Layouts or Windows used to draw custom graphics on top of Activities, the Frame, the Journal or any Sugar View. A more complete description for Probes and Overlays is given in the Tutorius Architecture document referred in the Documentation section.

The tutorius service in the sugar-session adds an Engine to execute tutorials, a registering mecanism to register and unregister Probes when Activities are started and stopped and a dbus interface to start and stop tutorials.

Those changes involve modifications of less than 100 lines of code in the existing Sugar code base to the following files:

  • sugar:bin/sugar-session (Add the tutorius service)
  • sugar:src/jarabe/frame/frame.py (Add an Overlay and a Probe)
  • sugar:src/journal/journalactivity.py (Add a Probe)
  • sugar-toolkit:src/sugar/activity/activity.py (Add a Probe)
  • sugar-toolkit:src/sugar/graphics/window.py (Add an Overlay)

In addition to the previous modifications:

  • The tutorius files should be found under the sugar.tutorius module.
  • Some icons will be added.
  • The tutorial will be stored under ./sugar/default/tutorius in the user home directory.

Tasks

  1. Define an exact script for the introduction tutorial
  2. Rebase the existing Tutorius code base on top of Sugar 0.88
  3. Create a reliable Overlay for all the different Views and the Frame
  4. Make the Message Bubble position relative to the screen size
  5. Make sure the current localization mecanism is reliable
  6. Add the logging screen option (See UI Mocks)
  7. Add the option item to replay the introduction tutorial (See UI Mocks)
  8. Produce a tutorial
  9. Translate the tutorial in French
  10. Write documentation for the translation team

The only risky item is the creation of a reliable Overlay for the different Views. For a technical description of what it involves, see Features/Introduction_Tutorial/Overlay. Any help from GTK gurus in the community is welcome, as our last attempt at this was unsuccessful.

UI Design

This tutorial should be accessible from the first login screen, right after the color selection, and from the option menu:

login1-300x226.png options-300x225.png

The tutorial will provide an overview of the Desktop, the Group and the Neighborhood Views as well as the Frame, the Journal, the Write and the Browse activity. Here are screenshots of what it might look like for some of them.

desktop-300x214.png neighborhood-300x214.png journal-300x216.png write-300x216.png

The information presented to the user will be essentially composed of bubble messages pointing at screen elements. Progress through the tutorial will be accomplished by the user clicking a next button at the bottom of the screen. Once the tutorial is over, the user will be brought back to the Desktop screen where she will be able to resume interacting with the system normally. At any time during the tutorial, the user can press the Stop button to interrupt the current tutorial and return to the place she was when she started the tutorial.

How To Test

Features/Introduction Tutorial/Testing


User Experience

The tutorial won't affect the regular workflow or experience for the platform other than providing a tutorial on the first connexion.

Dependencies

None.

Contingency Plan

Revert to the previous release behavior.

Documentation

The following document provides a high-level view of the Tutorius Architecture. The original system was more powerful since it allowed Creation and Sharing of tutorials from within Sugar also. However, for the purpose of this feature proposal and to ease integration, only the Execution of tutorials will be considered. For the time being, any reference to the Store, the Workshop, the Creator and the Remote may safely be ignored. They are kept in case a further integration of those tools is accepted by the community in a later release.

The execution scenarios presented are not completely up-to-date and will be revised in the next weeks. For the time being, the most interesting part should be the component diagrams and descriptions.

  • http://www.tutorius.org (Website for the project that ended on December 2009; now owned by a domain grabber)

Source Code

Forks of sugar components:

Release Notes

A default interactive tutorial is provided on the first login to help familiarize a new user to Sugar. This tutorial can also be replayed anytime from the option menu.

Comments and Discussion