Help system changes

I've been trying to clean up the help system a bit; starting with tidying the code side of things to make it easier to edit the content etc. Mostly I want to update some stuff- having an 'official' help page for Squeak 5.2 that tells people they need SqueakV64.sources is probably a bit unhelpful, for example.

Whilst digging through this I note some areas that might be improved and simplified. This really isn't a good time to be making huge changes but we can probably tidy up some.

1. Is it really best to have the current Help menu with a general HelpBrowser opening entry and then several menu items that open browsers on content that is within the general help? Yes, sort-of shortcuts, no, potential for confusion and drift

2. The general help is opened such that the content is displayed in a plain PluggableTextMorphPlus. Any pages displayed within the general help are plain text. However, the 'TerseGuide' and 'Useful Expressions' specific entries open help browsers that are set up with Shout styling. There's a couple issues with that
a) The content looks different in the two versions, which seems like a good way to engender some confusion in new users.
b) There really isn't any meaningful benefit I can see to using shout styling in either of these two places (I'm sure there are case where it would be important)
c) The choice is made in the the TheWorldMainDockingBar>>#commandKeyHelp and related methods, whereas it surely ought to be at least specific to the Help book, better yet specific to the topic and probably best of all, limited to sections of  pages where it is marked up to be styled.


For 1. I propose reducing the menu entries to Squeak Help, Release Notes & About Squeak. The only complication I see is adding the swiki based help book into the general help.

For 2. I suggest dropping the TheWorldMainDockingBar>>#openHelp:topic:styled: and just opening the general help browser. In the future I'd hope we can provide a markup facility to allow a section of text to be styled with Shout or indeed some other mechanism. Maybe we could extend the cmd-6 menu to add that.

Other ideas welcomed.

tim
--
tim Rowledge; [hidden email]; http://www.rowledge.org/tim
Strange OpCodes: UDF: Use Disk for Frisbee

> I've been trying to clean up the help system a bit; starting with tidying the code side of things to make it easier to edit the content etc. Mostly I want to update some stuff- having an 'official' help page for Squeak 5.2 that tells people they need SqueakV64.sources is probably a bit unhelpful, for example.

That sounds helpful to me, why is that unhelpful?

> Whilst digging through this I note some areas that might be improved and simplified. This really isn't a good time to be making huge changes but we can probably tidy up some.
>
> 1. Is it really best to have the current Help menu with a general HelpBrowser opening entry and then several menu items that open browsers on content that is within the general help? Yes, sort-of shortcuts, no, potential for confusion and drift

These are the shortcuts people want.  They reduce confusion for new
users, and returning users would want to access those frequently
either as a "refresher" or quick-access utility.  I see only goodness
here...

> 2. The general help is opened such that the content is displayed in a plain PluggableTextMorphPlus. Any pages displayed within the general help are plain text. However, the 'TerseGuide' and 'Useful Expressions' specific entries open help browsers that are set up with Shout styling. There's a couple issues with that
> a) The content looks different in the two versions, which seems like a good way to engender some confusion in new users.

If they're to be on their way to interacting with Squeak, I would
expect the executable code examples to be Shout styled, while the
non-code help to not (necessarily) be.

> b) There really isn't any meaningful benefit I can see to using shout styling in either of these two places (I'm sure there are case where it would be important)

They're code examples, Shout styling is tremendously beneficial.

> c) The choice is made in the the TheWorldMainDockingBar>>#commandKeyHelp and related methods, whereas it surely ought to be at least specific to the Help book, better yet specific to the topic and probably best of all, limited to sections of  pages where it is marked up to be styled.

I'm not sure what you're saying here.  Command-key help is one of the
first things both new and returning users look for, it should
_definitely_ remain on that menu.  I see no reason to slow new users
down from learning how to navigate and use the system with hot-keys
before they get around to opening up that help tome and get to
"Chapter 37 -- Hot Keys".  Please, no.

> For 1. I propose reducing the menu entries to Squeak Help, Release Notes & About Squeak. The only complication I see is adding the swiki based help book into the general help.

Yikes!  Why?

-1.

> For 2. I suggest dropping the TheWorldMainDockingBar>>#openHelp:topic:styled: and just opening the general help browser. In the future I'd hope we can provide a markup facility to allow a section of text to be styled with Shout or indeed some other mechanism. Maybe we could extend the cmd-6 menu to add that.

If they are to learn Squeak and OO, we should reinforce the idea that
paths to objects are *designed* based on _human_ needs, not merely one
grand root that forces you to navigate down a hierarchical path just
to ask how to open a browser with the keyboard.

> Other ideas welcomed.

How about getting that "Squeak Swiki" menu entry working well again?

> Other ideas welcomed.

Looks like the font summary window is not displaying them in their
respective fonts, either...

> On 04-06-2018, at 6:01 PM, Chris Muller <[hidden email]> wrote:
>
>> I've been trying to clean up the help system a bit; starting with tidying the code side of things to make it easier to edit the content etc. Mostly I want to update some stuff- having an 'official' help page for Squeak 5.2 that tells people they need SqueakV64.sources is probably a bit unhelpful, for example.
>
> That sounds helpful to me, why is that unhelpful?

Oh, I don't know, perhaps because it's factually incorrect? That seems a bit unhelpful to me.

[snip]
>
>> 2. The general help is opened such that the content is displayed in a plain PluggableTextMorphPlus. Any pages displayed within the general help are plain text. However, the 'TerseGuide' and 'Useful Expressions' specific entries open help browsers that are set up with Shout styling. There's a couple issues with that
>> a) The content looks different in the two versions, which seems like a good way to engender some confusion in new users.
>
> If they're to be on their way to interacting with Squeak, I would
> expect the executable code examples to be Shout styled, while the
> non-code help to not (necessarily) be.

You are making my argument for me about why the styling should not be decided at the gross level but at the 'retail' level.
>
>> b) There really isn't any meaningful benefit I can see to using shout styling in either of these two places (I'm sure there are case where it would be important)
>
> They're code examples, Shout styling is tremendously beneficial.

I disagree about the 'tremendously' part. And the problem part is the way that they are styled or not in surprising places, not particularly whether styled or  not.

>
>> c) The choice is made in the the TheWorldMainDockingBar>>#commandKeyHelp and related methods, whereas it surely ought to be at least specific to the Help book, better yet specific to the topic and probably best of all, limited to sections of  pages where it is marked up to be styled.
>
> I'm not sure what you're saying here.  Command-key help is one of the
> first things both new and returning users look for, it should
> _definitely_ remain on that menu.  I see no reason to slow new users
> down from learning how to navigate and use the system with hot-keys
> before they get around to opening up that help tome and get to
> "Chapter 37 -- Hot Keys".  Please, no.

Yet again you're completely and utterly missing the point of what was written. Read section c) again. It's *nothing* to do with whether 'command key help' should or should not be listed anywhere.

>
>> For 1. I propose reducing the menu entries to Squeak Help, Release Notes & About Squeak. The only complication I see is adding the swiki based help book into the general help.
>
> Yikes!  Why?

Reduction of redundant and unnecessarily repeated redundancy. Tastes may vary.

>
>> For 2. I suggest dropping the TheWorldMainDockingBar>>#openHelp:topic:styled: and just opening the general help browser. In the future I'd hope we can provide a markup facility to allow a section of text to be styled with Shout or indeed some other mechanism. Maybe we could extend the cmd-6 menu to add that.
>
> If they are to learn Squeak and OO, we should reinforce the idea that
> paths to objects are *designed* based on _human_ needs, not merely one
> grand root that forces you to navigate down a hierarchical path just
> to ask how to open a browser with the keyboard.

Yet again, completely and utterly missing the point. This is a suggestion to change the API the opens the help browser in such a way as to improve the readability of the help content by enabling Shout styling where you want it and detailed manual styling - like maybe bolding and italic and underlining - where you want it. Which would as a nice side-effect obviate the current unfortunate scenario of one route to seeing the TerseGuide content displaying it styled and the alternate route showing it completely plain.

tim
--
tim Rowledge; [hidden email]; http://www.rowledge.org/tim
Strange OpCodes: PFM: Pray For Miracle

>>> I've been trying to clean up the help system a bit; starting with tidying the code side of things to make it easier to edit the content etc. Mostly I want to update some stuff- having an 'official' help page for Squeak 5.2 that tells people they need SqueakV64.sources is probably a bit unhelpful, for example.
>>
>> That sounds helpful to me, why is that unhelpful?
>
> Oh, I don't know, perhaps because it's factually incorrect? That seems a bit unhelpful to me.

Tim, you mentioned an 'official' [sic] help page -- at first I thought
you meant the one presented by selecting, "Squeak Help".  But there's
no mention of the .sources file there, so I asked an honest question
for clarification.  Your response is, uh, unhelpful, and why I still
no idea what you're talking about.

A changeset or Inbox mcz is the easiest way to understand your
proposal, even if only an incomplete sketch.

 - Chris

On 6/5/18, Chris Muller <[hidden email]> wrote: And some screen shots ....

HH.

> On 04-06-2018, at 8:40 PM, Chris Muller <[hidden email]> wrote:

> [snip]
> Tim, you mentioned an 'official' [sic] help page -- at first I thought
> you meant the one presented by selecting, "Squeak Help".  But there's
> no mention of the .sources file there, so I asked an honest question
> for clarification.  Your response is, uh, unhelpful, and why I still
> no idea what you're talking about.

MenuBar->Help->The Project->Working with Squeak->3. The Sources File

Clear enough?
Or perhaps since you prefer everyone to read the code, SqueakProjectHelp class>>#workingWithSqueak


tim
--
tim Rowledge; [hidden email]; http://www.rowledge.org/tim
Strange OpCodes: XO: Execute Operator