Smalltalk › Pharo › Pharo Smalltalk Users

Smalltalk tutorial is broken

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

9 messages Options

horrido

Smalltalk tutorial is broken

So say many visitors to https://amber-lang.net/learn.html.

The problem is this: visitors are failing to read and comprehend the last instruction on the first page of the tutorial. The one that reads: Select the text below and click on the 'DoIt' button.

They're not selecting the text. They do not understand what is meant by "select the text below."

So they immediately encounter a parse error and conclude that the tutorial is broken. This is a horrible, horrible first impression for Smalltalk.

It's not a rare occurrence, either. I've received this complaint numerous times on Quora and Medium.

So the question is: How to fix this? How to avoid this PR nightmare?

Jerry Kott-3

Re: Smalltalk tutorial is broken

We have too many Bill Gates’s and too few Steve Jobs’s. ‘uglification of the world - it’s a universal trend’ (Unbearable Lightness of Being, 1984). Smalltalk community suffers from too few people in general. For every 10000 ‘ok’ worker you need one genius visionary to turn things upside down. It’s always going to be a struggle.

Feeling like being philosophical this morning...

On May 10, 2019, at 06:31, Richard Kenneth Eng <[hidden email]> wrote:

So say many visitors to https://amber-lang.net/learn.html.

The problem is this: visitors are failing to read and comprehend the last instruction on the first page of the tutorial. The one that reads: Select the text below and click on the 'DoIt' button.

They're not selecting the text. They do not understand what is meant by "select the text below."

So they immediately encounter a parse error and conclude that the tutorial is broken. This is a horrible, horrible first impression for Smalltalk.

It's not a rare occurrence, either. I've received this complaint numerous times on Quora and Medium.

So the question is: How to fix this? How to avoid this PR nightmare?

Christopher Fuhrman-3

Re: Smalltalk tutorial is broken

In reply to this post by horrido

On Fri, May 10, 2019, 15:32 Richard Kenneth Eng <[hidden email]> wrote:

So say many visitors to https://amber-lang.net/learn.html.

The problem is this: visitors are failing to read and comprehend the last instruction on the first page of the tutorial. The one that reads: Select the text below and click on the 'DoIt' button.
...

How to fix this? How to avoid this PR nightmare?

I can think of at least three easy solutions:

Change the button from "DoIt" to "do the selected text"

Change the first line to:

Profstef next "(you must select this entire line of text.)"

But the best one might be:

Catch the parse error and if it's a null, remind the user she must first select the text.

Ben Coman

Re: Smalltalk tutorial is broken

In reply to this post by horrido

A picture is worth a thousand words. What it needs is an animated GIF
on loop demonstrating what to do.

cheers -ben

On Fri, 10 May 2019 at 21:32, Richard Kenneth Eng
<[hidden email]> wrote:

>
> So say many visitors to https://amber-lang.net/learn.html.
>
> The problem is this: visitors are failing to read and comprehend the last instruction on the first page of the tutorial. The one that reads: Select the text below and click on the 'DoIt' button.
>
> They're not selecting the text. They do not understand what is meant by "select the text below."
>
> So they immediately encounter a parse error and conclude that the tutorial is broken. This is a horrible, horrible first impression for Smalltalk.
>
> It's not a rare occurrence, either. I've received this complaint numerous times on Quora and Medium.
>
> So the question is: How to fix this? How to avoid this PR nightmare?

jgfoster

Re: Smalltalk tutorial is broken

In reply to this post by Christopher Fuhrman-3

On May 10, 2019, at 8:53 AM, Christopher Fuhrman <[hidden email]> wrote:

On Fri, May 10, 2019, 15:32 Richard Kenneth Eng <[hidden email]> wrote:
So say many visitors to https://amber-lang.net/learn.html.

The problem is this: visitors are failing to read and comprehend the last instruction on the first page of the tutorial. The one that reads: Select the text below and click on the 'DoIt' button.
...
How to fix this? How to avoid this PR nightmare?
I can think of at least three easy solutions:

Change the button from "DoIt" to "do the selected text"

Change the first line to:
Profstef next "(you must select this entire line of text.)"

But the best one might be:
Catch the parse error and if it's a null, remind the user she must first select the text.

Some Smalltalk implementations auto-select the entire line if nothing is selected. I like that very much.

horrido

Re: Smalltalk tutorial is broken

Yes, I like that best, too. I wonder how hard it would be to add this to
Amber.

jgfoster wrote
>> On May 10, 2019, at 8:53 AM, Christopher Fuhrman <

> christopher.fuhrman@

> > wrote:
>>
>>
>> On Fri, May 10, 2019, 15:32 Richard Kenneth Eng <

> horrido.hobbies@

> <mailto:

> horrido.hobbies@

> >> wrote:
>> So say many visitors to https://amber-lang.net/learn.html
>> <https://amber-lang.net/learn.html>.
>>
>> The problem is this: visitors are failing to read and comprehend the last
>> instruction on the first page of the tutorial. The one that reads: Select
>> the text below and click on the 'DoIt' button.
>> ...
>> How to fix this? How to avoid this PR nightmare?
>> I can think of at least three easy solutions:
>>
>> Change the button from "DoIt" to "do the selected text"
>>
>> Change the first line to:
>> Profstef next "(you must select this entire line of text.)"
>>
>> But the best one might be:
>> Catch the parse error and if it's a null, remind the user she must first
>> select the text.
>
> Some Smalltalk implementations auto-select the entire line if nothing is
> selected. I like that very much.

--
Sent from: http://forum.world.st/Pharo-Smalltalk-Users-f1310670.html

horrido

Re: Smalltalk tutorial is broken

In reply to this post by Ben Coman

<http://forum.world.st/file/t128560/ProfStef.gif>

Ben Coman wrote
> A picture is worth a thousand words. What it needs is an animated GIF
> on loop demonstrating what to do.
>
> cheers -ben
>
> On Fri, 10 May 2019 at 21:32, Richard Kenneth Eng
> <

> horrido.hobbies@

> > wrote:
>>
>> So say many visitors to https://amber-lang.net/learn.html.
>>
>> The problem is this: visitors are failing to read and comprehend the last
>> instruction on the first page of the tutorial. The one that reads: Select
>> the text below and click on the 'DoIt' button.
>>
>> They're not selecting the text. They do not understand what is meant by
>> "select the text below."
>>
>> So they immediately encounter a parse error and conclude that the
>> tutorial is broken. This is a horrible, horrible first impression for
>> Smalltalk.
>>
>> It's not a rare occurrence, either. I've received this complaint numerous
>> times on Quora and Medium.
>>
>> So the question is: How to fix this? How to avoid this PR nightmare?

--
Sent from: http://forum.world.st/Pharo-Smalltalk-Users-f1310670.html

Ben Coman

Re: Smalltalk tutorial is broken

On Sat, 11 May 2019 at 07:33, horrido <[hidden email]> wrote:
>
> <http://forum.world.st/file/t128560/ProfStef.gif>

Looks good.
cheers -ben

>
>
> Ben Coman wrote
> > A picture is worth a thousand words. What it needs is an animated GIF
> > on loop demonstrating what to do.
> >
> > cheers -ben
> >
> > On Fri, 10 May 2019 at 21:32, Richard Kenneth Eng
> > <
>
> > horrido.hobbies@
>
> > > wrote:
> >>
> >> So say many visitors to https://amber-lang.net/learn.html.
> >>
> >> The problem is this: visitors are failing to read and comprehend the last
> >> instruction on the first page of the tutorial. The one that reads: Select
> >> the text below and click on the 'DoIt' button.
> >>
> >> They're not selecting the text. They do not understand what is meant by
> >> "select the text below."
> >>
> >> So they immediately encounter a parse error and conclude that the
> >> tutorial is broken. This is a horrible, horrible first impression for
> >> Smalltalk.
> >>
> >> It's not a rare occurrence, either. I've received this complaint numerous
> >> times on Quora and Medium.
> >>
> >> So the question is: How to fix this? How to avoid this PR nightmare?
>
>
>
>
>
> --
> Sent from: http://forum.world.st/Pharo-Smalltalk-Users-f1310670.html
>

tbrunz

Re: Smalltalk tutorial is broken

In reply to this post by horrido

I think the animation is much better than the idea of "if nothing is
selected, then auto-select the entire line".

The auto-select idea teaches bad habits, or it teaches something different
from how the UI normally works / is supposed to work.

And then you start a schism of Smalltalk UIs: Some that have this behavior
and some that don't, which leads to confusion -- and turns people off.

The GIF instructs visually, by example, how the UI works rather than
compensating for the user's lack of understanding. Much better!

-Ted

horrido wrote

> <http://forum.world.st/file/t128560/ProfStef.gif>
>
>
> Ben Coman wrote
>> A picture is worth a thousand words. What it needs is an animated GIF
>> on loop demonstrating what to do.
>>
>> cheers -ben
>>
>> On Fri, 10 May 2019 at 21:32, Richard Kenneth Eng
>> <
>
>> horrido.hobbies@
>
>> > wrote:
>>>
>>> So say many visitors to https://amber-lang.net/learn.html.
>>>
>>> The problem is this: visitors are failing to read and comprehend the
>>> last
>>> instruction on the first page of the tutorial. The one that reads:
>>> Select
>>> the text below and click on the 'DoIt' button.
>>>
>>> They're not selecting the text. They do not understand what is meant by
>>> "select the text below."
>>>
>>> So they immediately encounter a parse error and conclude that the
>>> tutorial is broken. This is a horrible, horrible first impression for
>>> Smalltalk.
>>>
>>> It's not a rare occurrence, either. I've received this complaint
>>> numerous
>>> times on Quora and Medium.
>>>
>>> So the question is: How to fix this? How to avoid this PR nightmare?
>
> --
> Sent from: http://forum.world.st/Pharo-Smalltalk-Users-f1310670.html

--
Sent from: http://forum.world.st/Pharo-Smalltalk-Users-f1310670.html