[squeak-dev] Help system changes

Chris Muller asqueaker at gmail.com
Tue Jun 5 01:01:59 UTC 2018

> 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

> 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?


> 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?

More information about the Squeak-dev mailing list