Progressive escalation of help

[Ilya Zakharevich]

          [Repost after a list resurrection]

As far as I understand, one of the principal usability features is
a "progressive escalation of help".  One does not want to drink from a
fire hydrant - unless any other option is exhausted.  One always wants
as little help as possible - as far as it DOES help.

In manuals, it appears, e.g., as distinction of user manual and reference
manual (2 stages of escalation; if manuals are good, they have stages
of escalation inside them as well).  In GUI, it is usually 3 stages:

 Toolbar icon ---> Couple-of-words in a tooltip ----> F1 to manual

 Couple-of-words on a   -----> Short sentence   ----> F1 to manual
 a button or menu entry        in a tooltip
 or a slider label

In Emacs, it appears as a requirement that the first line of documentation
of a function/variable should be readable by itself.

To make a long story short: 3 stages is, of course, not enough -
especially with applications which target SIMULTANEOUSLY professionals
and first-time-Linux-users.  (And many components of GIMP have as
little as 1 stage; consider user controls of script-fu-register.)  How
to create extra stages without making users to learn new paradigms?

If you think about it for a second, the solution would jump at you:
tooltips should be "gradually extensible" - when you press F1 with a
tooltip shown, the tooltip should expand to the next level; when all
the levels are exhausted, it should start the manual viewer.

Tooltips which "know how to expand" should have a visual feedback.
(IMO a small square with F1 in UR corner should be enough.)  Tooltips
which would "expand to manual" should be also visually distinguishable
(with something like "Press F1 to view manual", as in GIMP - only in
GIMP, this message is completely borken).

What is the least intrusive way to introduce this to GIMP?  What about:

  0) Remove "Press F1 to view manual" from tooltips unless GIMP knows
     that a manual is present, and knows to which page to jump.

        (Most annoying when GIMP already failed to start a manual
         system, and/or when a tooltip is shown on a Script-Fu UI
         element which DEFINITELY has no idea how to show a manual.)

  1)  Allow the UI-strings in script-fu-register to be lists instead of
      strings.  A list entry may be a string (to show as a tooltip),
      a list of the form (URL "http://...") - for the last element (may
      be a relative URL w.r.t. user manual, as in (URL "manual:gimpedit_paste")

  1a) Optionally: allow list entries of the form, e.g., (chrome "path_to_icon")
      to show iconic labels on SF-FOO UI elements, and/or combine icons
      with text on menu entries.

  1b) Lastly, allow one to inspect whether this functionality is present,
      so one can write

         (script-fu-register "my-foo"
           "My Foo"
           (my-escalating-help "Do Foo in all the corners" "Longer help" ...)
           ...  Same with SF-BAR labels
         )

      with my-escalating-help() returning the full list, or the first element
      depending on what script-fu-register understands.

  2) When this is implemented (is not it a very minor change?), start to
     add "gradually escalating help" to GIMP itself.

What do you think?
Ilya




_______________________________________________
Gimp-developer mailing list
Gimp-developer@...
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-developer

[peter sikking]

Ilya Zakharevich wrote:

> To make a long story short: 3 stages is, of course, not enough -
> especially with applications which target SIMULTANEOUSLY professionals
> and first-time-Linux-users.

I understand "first-time-Linux-users" as really newby linux desktop
users, not beginner-GIMP-users (we have no priority to design for
the latter).

the help is there to help with GIMP functionality. not to
help with the minimal differences of the linux desktop
with mac and windows UI.

so I am a bit stuck where the point is...

     --ps

         founder + principal interaction architect
             man + machine interface works

         http://mmiworks.net/blog : on interaction architecture





_______________________________________________
Gimp-developer mailing list
Gimp-developer@...
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-developer

[Sven Neumann]

On Fri, 2009-10-02 at 06:22 +0000, Ilya Zakharevich wrote:

>   0) Remove "Press F1 to view manual" from tooltips unless GIMP knows
>      that a manual is present, and knows to which page to jump.

Since GIMP offers to read the manual online, the manual is always
present. Or rather, it becomes rather difficult to tell whether it is
present or not. Same goes for the decision on whether the manual covers
this topic. The core knows nothing about that and the gather that
knowledge, it needs to download the manual index. The change you are
asking for is definitely not trivial. It might be easier to just fix the
manual so that it covers help for all help IDs.


Sven


_______________________________________________
Gimp-developer mailing list
Gimp-developer@...
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-developer

[Ilya Zakharevich]

On 2009-10-02, Sven Neumann <sven@...> wrote:
>>   0) Remove "Press F1 to view manual" from tooltips unless GIMP knows
>>      that a manual is present, and knows to which page to jump.

> Since GIMP offers to read the manual online, the manual is always
> present. Or rather, it becomes rather difficult to tell whether it is
> present or not.

This is a very sad situation.  Note that most of users won't be able
to install GIMP documentation locally [*], and in today's state of
mobility, people are very often without Internet access...

  [*] Try to understand how to get GIMP docs starting at

          http://www.gimp.org/windows/

      I could not...  (Most probably, *I* would be able to do it if I
      would not decide to restrict access to resources mentioned on
      www.gimp.org...  But most users would be stuck at this point...)

      Do not you find this "see above" very frustrating?

> Same goes for the decision on whether the manual covers
> this topic. The core knows nothing about that and the gather that
> knowledge, it needs to download the manual index.

So before the index is downloaded, the message in tooltips should
better be modified accordingly.  "More help MIGHT be available by
pressing F1" or some such...  And then, a need to download the index
should be clearly indicated to the user when F1 is pressed...

> The change you are asking for is definitely not trivial. It might be
> easier to just fix the manual so that it covers help for all help
> IDs.

Including all the scripts I'm going to write?!

Yours,
Ilya

_______________________________________________
Gimp-developer mailing list
Gimp-developer@...
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-developer

[Ilya Zakharevich]

On 2009-10-02, peter sikking <peter@...> wrote:
>> To make a long story short: 3 stages is, of course, not enough -
>> especially with applications which target SIMULTANEOUSLY professionals
>> and first-time-Linux-users.

> I understand "first-time-Linux-users" as really newby linux desktop
> users, not beginner-GIMP-users (we have no priority to design for
> the latter).

  [I suppose you reversed two alternatives; otherwise one gets into a
   remarkable situation, as in: ]

"GIMP developers do not care about beginner GIMP users"...  Quite a
bold statement...  I suppose it is not shared by all GIMP developers -
including you... ;-)

> the help is there to help with GIMP functionality. not to
> help with the minimal differences of the linux desktop
> with mac and windows UI.

No contest here...

> so I am a bit stuck where the point is...

The point was three-headed:

  First:  help should better be "more flexible" [*];

  Second: the API changes to support specification of
          variable-level-of-verbosity (and the actual code to
          implement it!) may be quite minuscule [**];

  Third:  GIMP is one of the few applications which explicitly supports
          escalation of help (via the sentence about F1 in tooltips).
          But the current implementation of this support adds more
          confusion than it actually helps.

Yours,
Ilya

[*] As the simplest example: try to add tooltips to "argument inputer"
    for a script registered with script-fu-register; more examples in
    OP.

[**] Text on a user control (or tooltip) should be a list of strings
     (instead of a string); to implement, only a minor modification of
     code supporting F1-on-tooltip is needed);


_______________________________________________
Gimp-developer mailing list
Gimp-developer@...
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-developer

[Sven Neumann]

On Wed, 2009-10-21 at 00:41 +0000, Ilya Zakharevich wrote:

> This is a very sad situation.  Note that most of users won't be able
> to install GIMP documentation locally [*], and in today's state of
> mobility, people are very often without Internet access...
>
>   [*] Try to understand how to get GIMP docs starting at
>
>  http://www.gimp.org/windows/
>
>       I could not...  (Most probably, *I* would be able to do it if I
>       would not decide to restrict access to resources mentioned on
>       www.gimp.org...  But most users would be stuck at this point...)

Oh, come on. If you click on the very first link on this page, you end
up on http://gimp-win.sourceforge.net/stable.html which lists installers
for all the available translations of the user manual for GIMP 2.6.


Sven


_______________________________________________
Gimp-developer mailing list
Gimp-developer@...
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-developer

[Ilya Zakharevich]

On 2009-10-21, Sven Neumann <sven@...> wrote:

>> This is a very sad situation.  Note that most of users won't be able
>> to install GIMP documentation locally [*], and in today's state of
>> mobility, people are very often without Internet access...
>>
>>   [*] Try to understand how to get GIMP docs starting at
>>
>>  http://www.gimp.org/windows/
>>
>>       I could not...  (Most probably, *I* would be able to do it if I
>>       would not decide to restrict access to resources mentioned on
>>       www.gimp.org...  But most users would be stuck at this point...)
>
> Oh, come on. If you click on the very first link on this page, you end
> up on http://gimp-win.sourceforge.net/stable.html which lists installers
> for all the available translations of the user manual for GIMP 2.6.

But the point was that I did not want to install GIMP!  I already had
it installed, and wanted just to add documentation...  "The
documentation" of this link clearly says:

  Note that the user manual is an extra package

So, obviously, I investigated OTHER links on this page...

Yours,
Ilya

_______________________________________________
Gimp-developer mailing list
Gimp-developer@...
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-developer

[Alexandre Prokoudine]

On Thu, Oct 22, 2009 at 1:39 AM, Sven Neumann wrote:

>> This is a very sad situation.  Note that most of users won't be able
>> to install GIMP documentation locally [*], and in today's state of
>> mobility, people are very often without Internet access...
>>
>>   [*] Try to understand how to get GIMP docs starting at
>>
>>         http://www.gimp.org/windows/
>>
>>       I could not...  (Most probably, *I* would be able to do it if I
>>       would not decide to restrict access to resources mentioned on
>>       www.gimp.org...  But most users would be stuck at this point...)
>
> Oh, come on. If you click on the very first link on this page, you end
> up on http://gimp-win.sourceforge.net/stable.html which lists installers
> for all the available translations of the user manual for GIMP 2.6.

IMO the real solution is to shop documentation with GIMP. I know we
probably don't have the manpower to, but it's the only solution that
will ever Just Work (TM).

Alexandre
_______________________________________________
Gimp-developer mailing list
Gimp-developer@...
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-developer

[Alexandre Prokoudine]

On Thu, Oct 22, 2009 at 7:03 PM, Alexandre Prokoudine wrote:

> IMO the real solution is to shop documentation with GIMP.

Ship, that is :)

Alexandre
_______________________________________________
Gimp-developer mailing list
Gimp-developer@...
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-developer

[Bill Y.]

>On Thu, Oct 22, 2009 at 7:03 PM, Alexandre Prokoudine wrote:
>
>> IMO the real solution is to shop documentation with GIMP.
>
>Ship, that is :)
>
>Alexandre

YES !!

And anyway label the gimp help as "additional packadge" is pure nonsense:
for complex graphic software as Gimp the help is not something
"additional" but is strictly needed





--
photocomix (via www.gimpusers.com)
_______________________________________________
Gimp-developer mailing list
Gimp-developer@...
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-developer

[Martin Nordholts-2]

On 10/25/2009 04:13 PM, photocomix wrote:
>> On Thu, Oct 22, 2009 at 7:03 PM, Alexandre Prokoudine wrote:
>>
>>> IMO the real solution is to shop documentation with GIMP.
>>
>> Ship, that is :)
>>
>> Alexandre
>
> YES !!

I agree, distributing documentation separately for a program
like GIMP never made much sense to me

 / Martin

--

My GIMP Blog:
http://www.chromecode.com/

_______________________________________________
Gimp-developer mailing list
Gimp-developer@...
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-developer

[Sven Neumann]

On Sun, 2009-10-25 at 16:19 +0100, Martin Nordholts wrote:

> On 10/25/2009 04:13 PM, photocomix wrote:
> >> On Thu, Oct 22, 2009 at 7:03 PM, Alexandre Prokoudine wrote:
> >>
> >>> IMO the real solution is to shop documentation with GIMP.
> >>
> >> Ship, that is :)
> >>
> >> Alexandre
> >
> > YES !!
>
> I agree, distributing documentation separately for a program
> like GIMP never made much sense to me

You are ignoring two facts here:

(1) The user manual is a separate project with its development cycle
    and release dates. If we really insist on shipping the manual
    with GIMP, then we would have to wait for the user manual to be
    ready. For GIMP 2.6 that would have meant to delay the release
    for almost a year.

(2) The user manual is a lot larger than the program itself. If we
    insisted on shipping the user manual with each release of GIMP,
    then installing a bug-fix for GIMP would require a download of
    about 275MB compared to the 16MB that you'd have to download
    now.

IMO you are making a problem here that does not any longer exist. Not
having a release of the user manual for 2.6 was indeed a problem, but
that has finally been solved recently. Instead of complaining we should
thank the GIMP documentation team for their hard work. And we should
thank Jernej for providing installers for the user manual.

It would be a good idea though to discuss what can be done to make sure
that help for 2.8 will be available around the time that 2.8 is
released. But this is a discussion that belongs to the gimp-docs
mailing-list.


Sven


_______________________________________________
Gimp-developer mailing list
Gimp-developer@...
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-developer

[Martin Nordholts-2]

On 10/25/2009 05:26 PM, Sven Neumann wrote:

> On Sun, 2009-10-25 at 16:19 +0100, Martin Nordholts wrote:
>> On 10/25/2009 04:13 PM, photocomix wrote:
>>>> On Thu, Oct 22, 2009 at 7:03 PM, Alexandre Prokoudine wrote:
>>>>
>>>>> IMO the real solution is to shop documentation with GIMP.
>>>>
>>>> Ship, that is :)
>>>>
>>>> Alexandre
>>>
>>> YES !!
>>
>> I agree, distributing documentation separately for a program
>> like GIMP never made much sense to me
>
> You are ignoring two facts here:

My reply was a bit hasty and I apologize. Thanks to the
documentation team and Jernej for their hard work.

Keeping the documentation online is in many ways a good idea.
There is one thing we could do better though. Right now
when pressing F1 without a locally installed copy of the
manual there is a dialog box that says "you don't have
a copy of the GIMP user manual installed" with a button
to go to the online manual. IMO we should take the user
directly to the online manual and not nag her with dialogs.

I've talked to guiguru about this previously and to get
this to work good is a more work than it initially feels
like.

 / Martin

--

My GIMP Blog:
http://www.chromecode.com/

_______________________________________________
Gimp-developer mailing list
Gimp-developer@...
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-developer

[Michael Schumacher]

Sven Neumann wrote:

> IMO you are making a problem here that does not any longer exist. Not
> having a release of the user manual for 2.6 was indeed a problem, but
> that has finally been solved recently. Instead of complaining we should
> thank the GIMP documentation team for their hard work. And we should
> thank Jernej for providing installers for the user manual.

The installers are created with Inoosetup, and this tools allows
downloadable parts. I've used this once for a small utility which was
updated frequently. This happened in a controlled environment, though.

I would rather see an additional page in the current installer than an
installer that's double or triple the current size.


Michael

--
    GIMP > http://www.gimp.org      | IRC: irc://irc.gimp.org/gimp
    Wiki > http://wiki.gimp.org     | .de: http://gimpforum.de
Plug-ins > http://registry.gimp.org |
_______________________________________________
Gimp-developer mailing list
Gimp-developer@...
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-developer

[Sven Neumann]

Ni,

On Sun, 2009-10-25 at 17:46 +0100, Martin Nordholts wrote:

> Keeping the documentation online is in many ways a good idea.
> There is one thing we could do better though. Right now
> when pressing F1 without a locally installed copy of the
> manual there is a dialog box that says "you don't have
> a copy of the GIMP user manual installed" with a button
> to go to the online manual. IMO we should take the user
> directly to the online manual and not nag her with dialogs.

We only show this dialog once. If you confirm that you want to use the
online version, then you won't see that dialog again. I don't think
that's too bad. The dialog makes it clear what's happening and it serves
as a hint that the manual can also be installed locally. Removing this
dialog would be a regression.


Sven


_______________________________________________
Gimp-developer mailing list
Gimp-developer@...
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-developer

[Martin Nordholts-2]

On 10/25/2009 08:13 PM, Sven Neumann wrote:
> We only show this dialog once. If you confirm that you want to use the
> online version, then you won't see that dialog again. I don't think
> that's too bad. The dialog makes it clear what's happening and it serves
> as a hint that the manual can also be installed locally. Removing this
> dialog would be a regression.

If the user presses F1 he is interested in getting help, not being
informed that the information he will be reading is not locally
installed.

The possibility to install the manual locally becomes
interesting if there is no internet connection for example.

 / Martin

--

My GIMP Blog:
http://www.chromecode.com/
_______________________________________________
Gimp-developer mailing list
Gimp-developer@...
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-developer

[Alexia Death-2]

On Sunday 25 October 2009 21:21:45 Martin Nordholts wrote:
> If the user presses F1 he is interested in getting help, not being
> informed that the information he will be reading is not locally
> installed.
True.
 
> The possibility to install the manual locally becomes
> interesting if there is no internet connection for example.
And thats where the poke is. when there is no internet connection, you cant
get a locally installable help either. Sort of a deadlock.

-- Alexia
_______________________________________________
Gimp-developer mailing list
Gimp-developer@...
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-developer

[Alexandre Prokoudine]

On 10/25/09, Martin Nordholts wrote:

> My reply was a bit hasty and I apologize. Thanks to the
> documentation team and Jernej for their hard work.

I don't think your reply was hasty :) Having documentation available
at once is actually expected.

Provided the documentation project is a separate one indeed, I see two
solutions:

1. Make it downloadable during installation, like Michael suggests.
2. Leave .exe files where they are now, but keep amount of clicks to
download .exe with docs as low as possible.

Option 1 needs suboptions for every supported language, perhaps.
That's a question to Jernej, I guess.

Alexandre
_______________________________________________
Gimp-developer mailing list
Gimp-developer@...
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-developer

[Ilya Zakharevich]

On 2009-10-25, Martin Nordholts <enselic@...> wrote:
> Keeping the documentation online is in many ways a good idea.

A bad idea for people who are most of the time on the road without
online access...

> There is one thing we could do better though. Right now
> when pressing F1 without a locally installed copy of the
> manual there is a dialog box that says "you don't have
> a copy of the GIMP user manual installed" with a button
> to go to the online manual.

A good thing.  Yet better thing would be have a button with "install
local copy".

Yet better would be if GIMP could try to check the connection, and
would stop showing "press f1 for help" if there is no local copy and
no connection...

> IMO we should take the user directly to the online manual and not
> nag her with dialogs.

If you think the dialogue is nagging, it is better to make a checkbox
"do not show this again, show online help directly".  AND, maybe,
never show the same dialogue in the same session.

Yours,
Ilya

_______________________________________________
Gimp-developer mailing list
Gimp-developer@...
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-developer

[Martin Nordholts-2]

On 10/25/2009 11:35 PM, Ilya Zakharevich wrote:
> If you think the dialogue is nagging, it is better to make a checkbox
> "do not show this again, show online help directly".  AND, maybe,
> never show the same dialogue in the same session.

It won't nag me less just because I can dismiss it for the future.
Either the dialog presents important information that I need to see,
or it doesn't and I don't need to see it.

These "Don't show this any more"-dialog boxes is a sign
of insecureness in the "personality" of the application. We
don't want GIMP to be like that, we want GIMP to be confident
it what it is doing.

Regards,
Martin

--

My GIMP Blog:
http://www.chromecode.com/

_______________________________________________
Gimp-developer mailing list
Gimp-developer@...
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-developer