[Sugar-devel] Purpose for Help Activity

[Tony Anderson]

Hi,

What is the purpose of help? In Windows, help is a method to find out 
how to accomplish a particular task using an application. It is not a 
means to learn how to use the computer or Windows.

The Help activity is a specialized reader for the Floss (pdf) manuals.
Unfortunately, the text in the Floss manuals was written for experienced 
computer users who were new to the XO and the Sugar.

I believe we need a Sugar activity to introduce the XO and Sugar to 
those who have no prior computing experience. Further, we need to use 
the 'learn to learn' approach we advocate for the XO, i.e. these 
materials should be designed for experimentation (trial and error) and 
collaborative learning. The beauty of the computer is that it provides 
instant feedback on whether you did something 'right' or not.

I also believe that use of screenshots, screencasts and icons can reduce 
the dependency of these materials on text. Another underutilized tool is 
audio. If the text instructions were spoken, any deployment would be 
able to provide the same instructions in the native language (the skill 
needed would be a speaker of the native language who also knows 
English). Incidentally, in deployments where English is a medium of 
instruction, using both versions can help children learn English.

Tony





 > Message: 3
 > Date: Tue, 16 Oct 2012 09:05:08 -0300
 > From: Gonzalo Odiard <gonzalo at laptop.org>
 > To: "S. Daniel Francis" <francis at sugarlabs.org>
 > Cc: Sugar-dev Devel <sugar-devel at lists.sugarlabs.org>
 > Subject: Re: [Sugar-devel] Purpose for Help Activity
 > Message-ID:
 > 	<CAJ+iPVRgkE8Qenkjc3dQv8dUfybjCzESdtg8qvRxv8HzfQvxng at mail.gmail.com>
 > Content-Type: text/plain; charset="iso-8859-1"
 >
 > Help issues are known and we need solve it,
 > but I don't agree with the proposed solution.
 >
 > The style can be changed with css, that is not a problem.
 >
 > The biggest problem we have today, is found people to write the help.
 > If we impose to a potential writer the work of learn docbook,
 > will be worst. And writing a docbook editor is not a trivial task.
 >
 > About having help content inside the activities,
 > probably is a good idea. We need think about:
 > * how enable the translation of that content (and how much disk space
 > will use if we have all the translations inside the activity)
 > * where put the content related to sugar (not activities)
 >
 > Gonzalo
 >
 > On Mon, Oct 15, 2012 at 10:03 PM, S. Daniel Francis
 > <francis at sugarlabs.org>wrote:
 >
 >> Hi,
 >>
 >> Looking at the Help activity, I see the following issues:
 >> - It looks very orange. A more integrated style is needed.
 >> - Activities should be documented independently of the help activity.
 >>
 >> (Not very related with my purpose but important for deploy a solution)
 >> - The documentation needs to be updated and Gonzalo told me about
 >> there were efforts to update it. ?Where are them?
 >>
 >> Now I purpose some solutions:
 >> - Using docbook.
 >> Docbook is used by the GNOME documentation team and can be styled
 >> easily with CSS.
 >> - Save the documentation in each activity.
 >> With that way, Help could scan each activity for documentation, that
 >> documentation could depend of the installed version of each activity.
 >> And documentation for non-core activities could be seen from the Help
 >> activity.
 >>
 >> Knowing that the Help isn't up to date, I only migrated the first
 >> chapter for give you a preview of my purpose.
 >>
 >> A screenshot:
 >> http://wiki.sugarlabs.org/go/File:Help-docbook-purpose.png
 >>
 >> On the git repository:
 >> http://git.sugarlabs.org/~danielf/help/help-docbook
 >>
 >> For generate the HTML files I used the following command: (Already
 >> generated in the repository)
 >> $ yelp-build html -o ./help/ sources.xml
 >>
 >> Warm regards,
 >> Daniel Francis.
 >>