[Sugar-devel] [IAEP] Working math graphs/plots

[Gary C Martin]

Hi Reinier,

On 17 Dec 2008, at 08:23, Reinier Heeres wrote:

> Hi Gary,
>
> I'm currently working on updating the Calculator. I built a new  
> expression parser (based on some python internals) that is about 10  
> times faster. This also makes plotting a whole lot more interesting,  
> since it was a bit slow before. I like the icon you drew; do you  
> have it as an SVG?

That one was just a quick mock-up, here's the real SVG :-)

-------------- next part --------------
A non-text attachment was scrubbed...
Name: plot.svg
Type: image/svg+xml
Size: 1220 bytes
Desc: not available
Url : http://lists.sugarlabs.org/archive/sugar-devel/attachments/20081217/1d564c78/attachment-0001.svg 
-------------- next part --------------


> I'm still not exactly sure where to fit it in, but perhaps I can  
> rename the 'Format' tab to 'Misc' or something, because currently  
> there are not many things there and I can always use a separator.

When I was making the plot SVG, I had a quick play folding the  
Constants (not much in there either) and Formats tab, into a new  
Miscellaneous tab with some separators:

-------------- next part --------------
A non-text attachment was scrubbed...
Name: calc-plot-screenshot.jpg
Type: image/jpeg
Size: 26290 bytes
Desc: not available
Url : http://lists.sugarlabs.org/archive/sugar-devel/attachments/20081217/1d564c78/attachment-0001.jpg 
-------------- next part --------------



Don't have a strong opinion about where Plot should really go (I was  
just trying to wean out a tab in the above case).

> Finally, if you have good ideas about how to better expose the help  
> texts I would be really interested too, since I agree with the  
> discussion that they could be better exposed.

I think we should lock Eben in a dark broom-cupboard somewhere until  
he comes up with a suitable HIG way of exposing (some level of) help :-)

There seem to be two levels of potential help content: A) activity  
usage tutorials/walkthroughs; B) help while you're poking your way  
around a UI. I'm focused on case B here, and for most activities I  
think B should be enough.

Some (likely biased) rambling approaches on the matter, in no  
particular order:

1) Add a standard help icon to every activities activity tab which  
brings up a modal sugarised dialogue box with a (scrollable) text view.

PROs
- visually discoverable
- lots of space for lots of text

CONs
- no space on activity tab for another icon (all that wasted "share  
with..." widgetry)
- not contextual!!!
- modal, so you can't see help and interact with UI!!
- I don't find single lumps of help text all that useful/pleasant :-)

2) Add a standard help icon to every activities activity tab, clicking  
it would make the cursor into a help cursor where the next click on  
some feature would reveal some help text (Carol hinted at this).

PROs
- visually discoverable

CONs
- no space on activity tab for another icon (all that wasted "share  
with..." widgetry)
- interaction method is a little complicated (changes cursor state,  
multiple clicks)
- would require a lot of retrofitting and you'd still need to visually  
indicate every item that has have some help otherwise the user is left  
frustratingly screen scrubbing with a ? cursor, perhaps digging to  
some UI element that might end up having no help any way (or force  
developers to add help to every visually distinct pile of pixels so  
the user always could find at least something).
- where does the actual help text appear (a hove pop-up, a help  
dialogue)

3) The 'Reinier' way, put a help item in a hover palette/menu that  
reveals help 'in some way'.

PROs
- context sensitive (and developers only have to add help for complex  
features)
- uses existing Sugar UI features

CONs
- Edward can't find it ;-b (not so easy to discover due to delayed  
reveal)
- the 'in some way' needs some work. In calculates specific case,  
inserting a help command into the calculator input is not great as it  
mangles the formula you were half way through and needed help on. The  
resulting help text answer display is also pretty truncated just now.

I'm still liking  option 3 the most. It requires no special sugar  
inventions, just some HIG from Eben so that activities have a standard  
style to aim for. Once a few activities use it, you'll know where to  
look if you need help elsewhere.

The 'in some way' could be resolved for a generic activity use case by:

3.1 Make the help item trigger a dialogue of some kind. This could be  
something new, or even just the non-modal alert dialogue as available  
in 8.2.

PROs
- enough room for a sentence or two of help

CONs
- needs testing, might have odd behaviours in real life ? do they  
stack if you have several alerts open?

3.2 Replace the help item with the actual help text, right there in  
the palette.

PROs
- help is just right there, no clicking, no pop-ups!

CONs
- non-standard use of menu/palette items (relative to other platforms,  
non functional menu text is frowned upon in most HIGs)
- limited quantity of help text (needs to be short and sweet or will  
look silly)
- will be confusing if a palette needs other real working items. Can  
inactive help text be styled? Italics perhaps?

Any other help suggestions out there? Shall we all go open trac  
tickets for Even and the HIG ;-)

Regards,
--Gary

> Cheers,
> Reinier
>
> Gary C Martin wrote:
>>
>> On 13 Dec 2008, at 05:55, Edward Cherlin wrote:
>>
>>> On Fri, Dec 12, 2008 at 8:50 PM, Gary C Martin  
>>> <gary at garycmartin.com> wrote:
>>>> On 13 Dec 2008, at 01:53, Edward Cherlin wrote:
>>>>
>>>>> On Wed, Dec 10, 2008 at 8:25 PM, Gary C Martin <gary at garycmartin.com 
>>>>> >
>>>>> wrote:
>>>>>>
>>>>>> On 11 Dec 2008, at 00:24, Edward Cherlin wrote:
>>>>>>
>>>>>>> On Wed, Dec 10, 2008 at 2:51 PM, Reinier Heeres <reinier at heeres.eu 
>>>>>>> >
>>>>>>> wrote:
>>>>>>>>
>>>>>>>> Hi,
>>>>>>>>
>>>>>>>> I agree that the plotting functionality is not really well  
>>>>>>>> exposed,
>>>>>>>> although help(index) will show you it's available and  
>>>>>>>> help(plot) will
>>>>>>>> tell you how to use it. Try plot(sin(x),x=0..360) for  
>>>>>>>> example. I'll
>>>>>>>> work
>>>>>>>> on the exposure of plotting in the next release; suggestions  
>>>>>>>> on how to
>>>>>>>> do this exactly would be welcome.
>>>>>>>
>>>>>>> Just exposing help would go a long way to solving the problem.
>>>>>>
>>>>>> Help is already exposed in the hover menu for each toolbar  
>>>>>> icon. Not
>>>>>> discoverable enough?
>>>
>>> OK, to be brutally explicit, I want a help icon on the toolbar,  
>>> with a
>>> menu of what you can get help on.
>>
>> Hmmm. I guess I'm just not a big fan of instructional text, but  
>> likely just a qwerk work mode of mine.
>>
>> However, I did once raise a suggestion that .xo and .xol bundles  
>> could be merged. Using Moon as an example, I could include  
>> something analogous to its wiki page content as part of the .xo  
>> download, that content would go into what is currently the library  
>> area accessed by browse (and removed again if you delete that  
>> activity). When updating an activity, you would then have a fair  
>> chance that its documentation was still correct for that version  
>> (unlike separate manual documentation efforts that quickly loose  
>> sync with what's shipping).
>>
>> This does put an unpleasant burden on translators, trying to keep  
>> up with document edits, and developers bothering to document new  
>> features. So it's always preferred to find ways to make an  
>> activities features obvious in the UI, and ditch instructional  
>> strings ('power' user features are allowed to be more obscure).
>>
>>>>> Absolutely not enough. I have to wait for the menu to expand  
>>>>> _twice_.
>>>>> How was I supposed to discover that?
>>>>
>>>> You could always read the Calculate wiki page, that's where I  
>>>> first read
>>>> about the plot feature ~11 months or so ago.
>>>
>>> Don't tell me what _I_ can do. Tell me what a non-English-speaking
>>> child in outback Cambodia without an Internet connection is supposed
>>> to do.
>>
>> Well in this case, help was there, built right in. Though not sure  
>> if strings are in Cambodian (but that's a large part of my issues  
>> regarding text in a UI). I agree that ways to make it more obvious  
>> and/or more standard between different activities would be a good  
>> thing.
>>
>>>> In the perfect world, every
>>>> feature you needed at any moment would be clearly represented in  
>>>> the UI.
>>>> Different individuals use software in different ways, it's always  
>>>> very hard
>>>> to get this right (and it's _never_ perfect).
>>>
>>> Imperfect I can deal with. Not there is beyond me.
>>
>> You're referring to plot() here I think, I can't see adding an icon  
>> for this being a major challenge, other than the general concern of  
>> feature snowballing (calculate has a lot of tool buttons already),  
>> but plotting in this case is a good feature show off :-)
>>
>>>>>> Seems Reinier' s Calculate has much more effort/detail
>>>>>> put in than any other activity so far.
>>>>>
>>>>> That doesn't mean that he got it right. I really, really hate  
>>>>> delayed
>>>>> hover menus, and I hate doubly-delayed hover menus many times  
>>>>> more.
>>>>
>>>> Being cheeky here... so right click and move on with life :-p
>>>
>>> No, I hadn't discovered that, either. :-D
>>
>> :-)
>>
>>>> (and, as a Mac
>>>> user, you have no idea how much it pained me when I first saw the  
>>>> project
>>>> was going for 2 mouse button use).
>>>
>>> I have taught preschool children click-and-drag and right click. I
>>> don't like them. I prefer one button, and click to grab, click to
>>> drop. At some age, two buttons and a set of game controls, or a
>>> programmer's third button, become practical. The question is the  
>>> ratio
>>> between effort of learning and effort saved working.
>>>
>>>> Sometimes I like the whole concept of hover menus, sometimes I  
>>>> think they
>>>> sucks. The idea is certainly going to have to be reworked (along  
>>>> with a
>>>> large chunk of the existing UI) if we get Sugar to a gen 2 touch  
>>>> interface.
>>>
>>> Has anybody here seen Hiroshi Ishii's Minority-Report-style UI? He
>>> showed at at the Engelbart-fest, Program for the Future.
>>
>> http://oblong.com/
>>
>> Seems plausible for a presenter/educator (like a TED talk), or very  
>> small group working together, but you'd only want to stand there  
>> waving your arms about for about 10-20min before getting back  
>> ache :-) I'd currently put it in the 'cool demo limited  
>> practicality' category.
>>
>>>>> First, because they are inherently not discoverable, and secondly,
>>>>> because you are wasting my time, and every other user's time. I  
>>>>> reject
>>>>> the argument that we are trying to teach children to click icons
>>>>> directly, and note that it doesn't even apply in the case of help.
>>>>
>>>> For me, I always consider the need for help text (and manuals) to  
>>>> be a level
>>>> of failure in design. Help texts are a large burden on everyone  
>>>> (quality,
>>>> translation, UI space, updates, accuracy), but often are the  
>>>> cheapest first
>>>> pass when you realise some feature not discoverable enough.
>>>>
>>>> Any concrete UI suggestions for calculate features (or  
>>>> activities** in
>>>> general) to be more discoverable for you?
>>>
>>> Answer given above. _Every_ option should be discoverable visually.
>>
>> Should, but we're back to talking about perfection again.
>>
>>> Forget hover.
>>
>> If you consider hover palettes as 'help hints', they are very  
>> widely used on other environments. Successfully I think. Hover is  
>> also a fair place to put power users features, so you don't clutter  
>> up the main functionality of an interface.
>>
>>> If a command must take an option, put the options on the
>>> menu for the item and just let me click it.
>>
>> I didn't quite follow this one. With the plot example, would  
>> something like this suffice?
>>
>>
>>
>> <mime-attachment.jpeg>
>>
>>
>>
>> (Reinier: shout if you like the idea, I'll make the SVG)
>>
>> The "plot(f(x),x=start..end)" could actually be replaced with  
>> several working examples that paste in their text (I'm sure a  
>> teacher needs to chip in provide us some better examples here):
>>
>>     plot(sin(x),x=0..360)
>>     plot(cos(x),x=0..360)
>>     plot(tan(x),x=0..360)
>>     plot(sqrt(x),x=0..10)
>>
>>>> You're not allowed to add this as
>>>> another potential FLOSS book TODO ;-) Well OK, I guess that might  
>>>> be a
>>>> workaround if there's no better UI effort (and teachers like  
>>>> static books,
>>>> right?).
>>>
>>> No!!! No FLOSS Manuals for what should be obvious.
>>
>> Manuals are usually for covering the non obvious, surely? Other  
>> than perhaps manuals that are more like walk simple throughs (mini- 
>> recipes), showing how one might use a tool to step by step to solve  
>> a given problem. I guess I'm not clear on what/how you are trying  
>> to document.
>>
>>> Make it
>>> sufficiently obvious, or add a tutorial, if you are going to do
>>> non-standard things with mice and menus. No, scratch that. Just make
>>> it obvious.
>>>
>>> I am about to start writing digital textbooks. I need the tools to
>>> stay out of the way so I can teach _ideas_.
>>
>> So these are books with noting to do with teaching Sugar/ 
>> Activities, right? But you might use Activities to help get across  
>> some of the ideas (one aspect of what makes digital books better  
>> than hard copy books)?
>>
>> I guess the best solution would be the hypercard like ideas, where  
>> a digital book was an easily integrated stack of potentially active  
>> components (etoys has an intersting 'book mode' but it's been too  
>> slow and memory hungry for me so far, along with the current slow  
>> writing to Journal when stopped). I guess OLE was another push in  
>> this direction.
>>
>> Probably the cheapest/fastest solution right now would be just  
>> making DHTML books (html and javascript for the interactive stuff),  
>> that would work as is, and pretty fast on the XO, but this needs  
>> authors who can actually code some javascript. The more Sugary  
>> solution should be to create digital books as Activities, that is  
>> you specifically create a Python activity template that's good for  
>> at least text/images, authors can than write the main book content,  
>> and custom chunks of python code can be written for the bits of  
>> interactive magic.
>>
>> Maybe being able to auto launch an activity state from an html  
>> document will be enough (once security concerns are resolved), but  
>> it's a pity we got hooked up on writing full Activities  
>> (applications), rather than sets of activity modules/widgets that  
>> could be plugged together to make larger custom documents.
>>
>> Imagine a lesson document about shapes, where each of the  
>> illustrations was actually an embedded TurtleArt widget that you  
>> could edit/tweak (clicking a widget would change the toolbar to  
>> that of the widgets); perhaps some of the maths examples would be  
>> shown in calculate widgets showing the working history to an  
>> answer; there could be little text areas made from Write widgets  
>> that you could type in to keep notes or write answers. Closing the  
>> document would keep state for any embedded widget changes, so it  
>> could be resumed and continued later. You may have interacted with  
>> half a dozen activity widgets for that lesson document, but you'd  
>> have created only one journal entry for your work. That journal  
>> entry could be synchronously (or asynchronously) shared with the  
>> teacher for checking/marking.
>>
>> Sorry, I'm beginning to waffle :-)
>>
>> Regards,
>> --Gary
>>
>>>> ** my latest casual discovery was that Write has customised its  
>>>> keep toolbar
>>>> icon, so if you hover you can choose to keep a copy as RTF, HTML,  
>>>> or plain
>>>> text. Well hidden, but this could be extended to 'keep' to all  
>>>> kind's of
>>>> interesting places (i.e. push to a Moodle server, an outbound  
>>>> email, web
>>>> site upload). Hopefully some Journal 'sharing'  feature will be a  
>>>> generic
>>>> solution for any activity.
>>>>
>>>> --Gary
>>>>
>>>>> My general principle of UI design is, never, ever try to be  
>>>>> smarter
>>>>> than your user. Not even if you are. Now that I know that help  
>>>>> is on
>>>>> the menus on double delay, I will almost never use it that way,
>>>>> because typing is faster, but I will resent it every time I have  
>>>>> to
>>>>> type it, because the menu could be faster.
>>>>>>
>>>>>> --Gary
>>>
>>> -- 
>>> Silent Thunder (??/ 
>>> ???????????????/ 
>>> ????????????? ?) is my name
>>> And Children are my nation.
>>> The Cosmos is my dwelling place, The Truth my destination.
>>> http://wiki.sugarlabs.org/go/User:Mokurai
>>
>
> -- 
> Reinier Heeres
> Waalstraat 17
> 2515 XK Den Haag
> The Netherlands
>
> Tel: +31 6 10852639