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 <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; mailto:tim at rowledge.org; 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/1662b19b/attachment.html>