[squeak-dev] Help system changes
tim at rowledge.org
Tue Jun 5 02:31:43 UTC 2018
> On 04-06-2018, at 6:01 PM, Chris Muller <asqueaker at gmail.com> 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.
>> 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 Rowledge; tim at rowledge.org; http://www.rowledge.org/tim
Strange OpCodes: PFM: Pray For Miracle
More information about the Squeak-dev