<div id="__MailbirdStyleContent" style="font-size: 10pt;font-family: Arial;color: #000000;text-align: left" dir="ltr">
                                        Hi Timothy --<div><br></div><div><span style="font-family: Verdana, Arial, Helvetica, sans-serif;">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.</span><br></div><div><br></div><div>> <span style="font-family: Verdana, Arial, Helvetica, sans-serif;font-size: 10pt">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.</span></div><div><span style="font-family: Verdana, Arial, Helvetica, sans-serif;font-size: 10pt"><br></span></div><div><span style="font-family: Verdana, Arial, Helvetica, sans-serif;font-size: 10pt">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</span><span style="font-family: Verdana, Arial, Helvetica, sans-serif;font-size: 10pt"> "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.</span></div><div><br></div><div><span style="font-family: Verdana, Arial, Helvetica, sans-serif;font-size: 10pt">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.</span></div><div><span style="font-family: Verdana, Arial, Helvetica, sans-serif;font-size: 10pt"><br></span></div><div><div><span style="font-family: Verdana, Arial, Helvetica, sans-serif;font-size: 10pt">***</span><br></div></div><div><span style="font-family: Verdana, Arial, Helvetica, sans-serif;font-size: 10pt"><br></span></div><div><span style="font-family: Verdana, Arial, Helvetica, sans-serif;font-size: 10pt">> </span><span style="font-family: Verdana, Arial, Helvetica, sans-serif"><span style="font-size: 10pt">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 </span><span style="font-size: 13.3333px">preliminary</span><span style="font-size: 10pt"> study will slim down my exploration time </span></span><span style="font-family: Verdana, Arial, Helvetica, sans-serif;font-size: 10pt">by presenting at a glance, What has preferences and in the scope of What has, What does it do.</span></div><div><span style="font-family: Verdana, Arial, Helvetica, sans-serif;font-size: 10pt"><br></span></div><div><span style="font-family: Verdana, Arial, Helvetica, sans-serif;font-size: 10pt">Totally. Different. Story. :-) Not like documenting, e.g., XMLDocument at all.</span></div><div><span style="font-family: Verdana, Arial, Helvetica, sans-serif;font-size: 10pt"><br></span></div><div><span style="font-family: Verdana, Arial, Helvetica, sans-serif;font-size: 10pt">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.</span></div><div><span style="font-family: Verdana, Arial, Helvetica, sans-serif;font-size: 10pt"><br></span></div><div><span style="font-family: Verdana, Arial, Helvetica, sans-serif">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.</span></div><div><span style="font-family: Verdana, Arial, Helvetica, sans-serif"><br></span></div><div><span style="font-family: Verdana, Arial, Helvetica, sans-serif">We want to teach domain vocabulary, not each domain's configuration space (i.e., not the preferences).</span></div><div><span style="font-family: Verdana, Arial, Helvetica, sans-serif"><br></span></div><div><span style="font-family: Verdana, Arial, Helvetica, sans-serif">***</span></div><div><span style="font-family: Verdana, Arial, Helvetica, sans-serif"><br></span></div><div><span style="font-family: Verdana, Arial, Helvetica, sans-serif">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.</span></div><div><span style="font-family: Verdana, Arial, Helvetica, sans-serif"><br></span></div><div><span style="font-family: Verdana, Arial, Helvetica, sans-serif">Here are the wizard pages:</span></div><div><span style="font-family: Verdana, Arial, Helvetica, sans-serif"><br></span></div><div><span style="font-family: Verdana, Arial, Helvetica, sans-serif"><span style="font-size: 13.3333px">#initializePage01Themes</span></span></div><div><span style="font-family: Verdana, Arial, Helvetica, sans-serif"><span style="font-size: 13.3333px">#initializePage02Visuals</span></span></div><div><span style="font-family: Verdana, Arial, Helvetica, sans-serif"><span style="font-size: 13.3333px">#initializePage02bVisualsMore</span></span></div><div><span style="font-family: Verdana, Arial, Helvetica, sans-serif"><span style="font-size: 13.3333px">#initializePage03Interaction</span></span></div><div><span style="font-family: Verdana, Arial, Helvetica, sans-serif"><span style="font-size: 13.3333px">#initializePage04InteractionMore</span></span></div><div><span style="font-family: Verdana, Arial, Helvetica, sans-serif"><span style="font-size: 13.3333px">#initializePage05Tools</span><br></span></div><div><span style="font-family: Verdana, Arial, Helvetica, sans-serif"><span style="font-size: 13.3333px"><br></span></span></div><div><span style="font-family: Verdana, Arial, Helvetica, sans-serif"><span style="font-size: 13.3333px">***</span></span></div><div><span style="font-family: Verdana, Arial, Helvetica, sans-serif"><span style="font-size: 13.3333px"><br></span></span></div><div><span style="font-family: Verdana, Arial, Helvetica, sans-serif"><span style="font-size: 13.3333px">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.</span></span></div><div><br></div><div><span style="font-family: Verdana, Arial, Helvetica, sans-serif;font-size: 10pt">Best,</span></div><div><span style="font-family: Verdana, Arial, Helvetica, sans-serif;font-size: 10pt">Marcel</span></div><div><br></div><div><br></div><div class="mb_sig"></div>
                                        <blockquote class="history_container" type="cite" style="border-left-style: solid;border-width: 1px;margin-top: 20px;margin-left: 0px;padding-left: 10px;min-width: 500px">
                        <p style="color: #AAAAAA; margin-top: 10px;">Am 29.11.2021 14:48:45 schrieb gettimothy <gettimothy@zoho.com>:</p><div style="font-family:Arial,Helvetica,sans-serif"><div style="font-family: Verdana, Arial, Helvetica, sans-serif;font-size: 10pt"><div>Hi Marcel<br></div><div><br></div><div>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.<br></div><div><br></div><div>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.<br></div><div>I offer back in case somebody finds the idea intriguing or useful.</div><div><br></div><div>Ideally, and I have no idea how this would happen, the atomized things "should" organize themselves into the big-picture documentation.<br></div><div>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.<br></div><div>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 <br></div><div>coalesce the thing into something I can use go forward.<br></div><div><br></div><div><div><br></div><div>Doc is baby steps in that direction as I think about the problem going forward.<br></div><div><br></div><div><br></div></div><div>That work , I can import to CustomHelp useing the Doc converters and it is readily available when I need it.<br></div><div>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 (:)<br></div><div><br></div><div>Squeak loses mind-share because of "the documentation problem" and that needs to be corrected because it is a beautiful coding idiom.<br></div><div><br></div><div><br></div><div>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<br></div><div>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.<br></div><div><br></div><div>Cordially,</div><div><br></div><div><br></div><div><br></div><div><br></div><div><br></div><div><br></div><div><br></div><div><br></div><div class="zmail_extra_hr" style="border-top: 1px solid rgb(204, 204, 204); height: 0px; margin-top: 10px; margin-bottom: 10px; line-height: 0px;"><br></div><div class="zmail_extra" data-zbluepencil-ignore="true"><div><br></div><div id="Zm-_Id_-Sgn1">---- On Mon, 29 Nov 2021 03:31:39 -0500 <b>Marcel Taeumel <marcel.taeumel@hpi.de></b> wrote ----<br></div><div><br></div><blockquote style="margin: 0px;min-width: 500px"><div><div id="x_-355037782__MailbirdStyleContent" style="font-size: 10pt;font-family: Arial;color: #000000;text-align: left" dir="ltr"><div>Hi all --<br></div><div><br></div><div>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.<br></div><div><br></div><div>***<br></div><div><br></div><div>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. :-)<br></div><div><br></div><div>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. ;-)<br></div><div><br></div><div>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.<br></div><div><br></div><div>Thank you.<br></div><div><br></div><div>Best,<br></div><div>Marcel<br></div><div><br></div><div>P.S.: The preference wizard is good for browsing. The preference browser is good for searching. Hehe. :-)<br></div><div class="x_-355037782mb_sig"><br></div><blockquote class="x_-355037782history_container" style="border-left-style: solid;border-width: 1px;margin-top: 20px;margin-left: 0px;padding-left: 10px;min-width: 500px"><p style="margin-top: 10px;"><span class="colour" style="color: rgb(170, 170, 170); margin-top: 10px;">Am 29.11.2021 01:24:11 schrieb David T. Lewis <<a href="mailto:lewis@mail.msen.com" target="_blank">lewis@mail.msen.com</a>>:</span><br></p><div style="font-family :  Arial, Helvetica, sans-serif;">It works. I highlighted 'TerseGuideHelp' and hit 6 to select<br>'Link to Help' and the resulting hyperlink opens the terse guide help.<br><br>Dave <br><br>On Sun, Nov 28, 2021 at 02:46:24PM -0800, tim Rowledge wrote:<br>> OK, a few more minutes banging randomly on a keyboard before lunch and I can offer this very simple idea as an example - <br><br><br>> <br>> <br>> <br>> <br>> > On 2021-11-27, at 8:29 PM, tim Rowledge  wrote:<br>> > <br>> > 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.<br>> > <br>> <br>> <br>> tim<br>> --<br>> tim Rowledge; <a href="mailto:tim@rowledge.org" target="_blank">tim@rowledge.org</a>; <a href="http://www.rowledge.org/tim" target="_blank">http://www.rowledge.org/tim</a><br>> Strange OpCodes: VDP: Violate Design Parameters<br>> <br>> <br><br>> <br><br><br></div></blockquote></div><div><br></div></div></blockquote></div><div><br></div></div><br></div></blockquote></div>