Hi Timothy --

I think we should optimize for how users can discover and understand the system's domain concepts first and foremost. Digging into a single concept's configuration space (i.e., its preferences) comes second if at all. The wizard tries to improve the first impression and to "smooth out the big determents" such as colors. Hehe.


> While I agree, and maybe I am missing something here, but a per-thing documentation approach, while valuable, does not lend itself to "big picture" use patterns.

Yes, the "big picture" can be challenging to document. If you are lucky, there is a "thing" in the system that represents the bigger idea. In Morphic, for example, I can attach generic documentation to the "Morph" class as well. Maybe within that documentation point to "MorphicEventDispatcher" to keep going. The "DOCUMENTATION" protocol in RxParser class is also very close to the "thing" it documents. For XML, the XMLDocument would be my personal point of entry when wanting to learn about XML support. In its class comment, you could point to other classes of interest. Maybe take a look at FFI's "ExternalPool" class comment.

Sure, if that is not possible or feasible, a documentation-only "thing" can be introduced like a "CustomHelp" class. Yet, that's harder to maintain and integrate. :-) Unless derived from existing information automatically such as in ClassAPIHelpTopic. Could work for preferences, too. There is a lot of existing documentation (i.e., texts) to expose/integrate.

***


> Now, this "preferences help" is my way of beginning to grok the big picture about Preferences via reading it, vs discovering it. Going forward, this preliminary study will slim down my exploration time by presenting at a glance, What has preferences and in the scope of What has, What does it do.

Totally. Different. Story. :-) Not like documenting, e.g., XMLDocument at all.

I think that if a user wants to change a preference about, say, "keyboard shortcuts", they can type "keyboard" and/or "shortcuts" in the search field and quickly browse the list of results. Not that hard. Typing "workspace" right now produces good results. Try it. The primary challenge is how to teach that vocabulary in the first place. And to attach that vocabulary to the searched space.

The PreferenceWizard simplifies things a bit. Keeping it browse-able. And teaches important vocabulary at the same time. After looking through the things in the wizard, you might be able to type in better queries in the preferences browser to find more preferences.

We want to teach domain vocabulary, not each domain's configuration space (i.e., not the preferences).

***

Okay. Say that you want to write/hard-code a new help topic to teach people about relevant preferences. Maybe take the wizard's approach into consideration and argue for or against it. If you find better categories, then we can also improve the wizard.

Here are the wizard pages:

#initializePage01Themes
#initializePage02Visuals
#initializePage02bVisualsMore
#initializePage03Interaction
#initializePage04InteractionMore
#initializePage05Tools


***

So, we have to teach users about the system's vocabulary. Then they can enter useful queries into search fields such as the one in the PreferenceBrowser. Then they can find what they are looking for. That's why I pointed to optimizing preference descriptions etc. Same goes for the HelpBrowser. Add topics that aggregate existing infos in a meaningful way to extend the search space. Keep the amount of topics with hand-crafted content to a minimum.

Best,
Marcel


Am 29.11.2021 14:48:45 schrieb gettimothy <gettimothy at zoho.com>:
Hi Marcel


While I agree, and maybe I am missing something here, but a per-thing documentation approach, while valuable, does not lend itself to "big picture" use patterns.


While I do not really care if Doc is incorporated into squeak someday, I use it precicely for these big-picture things so that I can understand a package.

I offer back in case somebody finds the idea intriguing or useful.

Ideally, and I have no idea how this would happen, the atomized things "should" organize themselves into the big-picture documentation.

However, getting Xtreams-Parsing to ask the PEG grammars, PEGActors etc to organize themselves into an explanation of how to use the thing is beyond my skills.

Same for XMLSax/Parser/Document/Node etc. So, before "flailing around" looking for relationships between classes/methods/objects, I start documenting in words, in Emacs and 

coalesce the thing into something I can use go forward.



Doc is baby steps in that direction as I think about the problem going forward.



That work , I can import to CustomHelp useing the Doc converters and it is readily available when I need it.

Pretty every question answered here by the team ends up in Doc-SqueakHOWTO for me to use later (Eliot, your method of substring extraction from a stream is next (:)


Squeak loses mind-share because of "the documentation problem" and that needs to be corrected because it is a beautiful coding idiom.



Now, this "preferences help" is my way of beginning to grok the big picture about Preferences via reading it, vs discovering it.  Going forward, this prelimary study will slim down my exploration time

by presenting at a glance, What has preferences and in the scope of What has, What does it do. Also, I was observing a discussion on Preferences and thought it would be a win-win for me and the team IF they choose to use any of it.


Cordially,










---- On Mon, 29 Nov 2021 03:31:39 -0500 Marcel Taeumel <marcel.taeumel at hpi.de> wrote ----


Hi all --


Please let us all improve the in-image documentation, which should be as close as possible to the things they document. At best, "these things" document themselves through their name or other distinctive features.


***


If you have an idea on how to clarify the description of a preference, go ahead and do it. Or at least mention it on this list. :-)


If you have an idea on a new category (or tag) for a preference, go ahead and add it. Or at least mention it on this list. ;-)


All this textual data is (or is expected to be) covered by the search feature in the PreferenceBrowser. So, if you favorite buzzword is not part of that data, consider adding it in the description, name, or category/tag list of that preference.


Thank you.


Best,

Marcel


P.S.: The preference wizard is good for browsing. The preference browser is good for searching. Hehe. :-)


Am 29.11.2021 01:24:11 schrieb David T. Lewis <lewis at mail.msen.com [mailto:lewis at mail.msen.com]>:

It works. I highlighted 'TerseGuideHelp' and hit 6 to select
'Link to Help' and the resulting hyperlink opens the terse guide help.

Dave

On Sun, Nov 28, 2021 at 02:46:24PM -0800, tim Rowledge wrote:
> OK, a few more minutes banging randomly on a keyboard before lunch and I can offer this very simple idea as an example -


>
>
>
>
> > On 2021-11-27, at 8:29 PM, tim Rowledge wrote:
> >
> > Hmm, a few minutes whacking suggests that a simple subclass of TextAction would do the job, along with a bit more understanding of the right way to open a help browser on a suitable topic. Maybe tomorrow.
> >
>
>
> tim
> --
> tim Rowledge; tim at rowledge.org [mailto:tim at rowledge.org]; http://www.rowledge.org/tim [http://www.rowledge.org/tim]
> Strange OpCodes: VDP: Violate Design Parameters
>
>

>





-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20211129/7d9ddc63/attachment.html>