Hi all --

I am not quite sure, what the overall goal is here. :-) "HelpBrowser+Seaside" sounds like a regular, web-based wiki, which be already have: wiki.squeak.org.

Squeak's help browser is in a pretty good shape to author, version, and share content for Squeak Trunk. The only downside is Monticello's full-method merge algorithm, making it hard to jointly improve a piece of writing. Yet, one does not have to store help content in methods. Files work, too. And so do pages via wiki.squeak.org.

If there are not that many authors for a piece of writing, I would suggest using the status quo -- favoring Help Browser (via methods) over Class Comments.

If there are several authors, just create a page on wiki.squeak.org and start writing. Then create a new entry for Squeak's Help Browser, specifically fetching that wiki page in a new help book/page. While this would likely be read-only from within the image, people could edit that through the Web front-end easily.

This would also work with any other wiki. Squeak's Help Browser could easily be used as a "reader" for such important wiki pages. And a common entry point to look for important information from within the image.

***

The help content should be as close as can be to the artifacts it is going to provide help for.

Best,
Marcel

P.S.: We could easily extend the MCMcmUpdater to give a special notification for new help content. :-)

Am 17.07.2021 20:48:47 schrieb David T. Lewis <lewis at mail.msen.com>:
On Sat, Jul 17, 2021 at 10:23:02AM -0400, Ron Teitelbaum wrote:
> Hi Herbert,
>
> Yeah, I thought that too and I'm sure the poll works that way but this
> is not scientific.
>
> Everyone,
>
> I took a look at the help browser and noticed that on the first page there
> is inaccurate information. Then I tried to search and hit a wide character
> error. Could have just been our UTF-8 version so I wondered if people are
> using it. I would like to see some more responses but it seems from the
> responses so far that this may be a viable solution.
> https://forms.gle/CsEpHvipoGbeud9k8
>
> Do we have a documentation team? If so, who is on it?
>
> To make the help browser more visible I think we need to have the ability
> to produce an online version to increase visibility but that seems like a
> doable project. Create an export, write some CSS, find a place to publish
> it, and we have something that can be found online. We may still be able
> to combine the help browser and use it as the source for something like
> https://www.sphinx-doc.org/en/master/ for the online version.
>
> If you have suggestions or ideas about a documentation project please speak
> up.
>
> So far the requirements are:
>
> 1. We need something that is easy enough for people to contribute.
> 2. Something that is easily maintained and modified
> 3. Something that is collaborative
> 4. Something that is easily discoverable
> 5. Something that is not easily ignored
> 6. Something that can be tested!
> 7. Something that can be versioned
>
> Thank you for your help!!
>

I would be happy to see a HelpBrowser/Seaside solution that does not
require a lot of new content creation. That said, I have to give a
shout out to the Cuis Book as an outstanding example of good writing
and content packaging. You can read the book on line or as a PDF, and
it is a very good piece of work either way.

The project is:
http://lists.squeakfoundation.org/pipermail/squeak-dev/2021-July/216008.html

which links to the on line book here:
http://lists.squeakfoundation.org/pipermail/squeak-dev/2021-July/216008.html

Dave


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20210719/2c264fb8/attachment.html>