[squeak-dev] Documenting the system

Ron Teitelbaum ron at usmedrec.com
Sat Jul 17 14:23:02 UTC 2021


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!!

Ron Teitelbaum

On Sat, Jul 17, 2021 at 6:42 AM Herbert König <herbertkoenig at gmx.net> wrote:

> I think this needs to allow for more possible paths.
> Example:
> Do you use the help browser? --> No
> Do you find the information in the help browser accurate? --> Mandatory ??
>
> Cheers,
>
> Herbert
>
> Am 16.07.2021 um 22:27 schrieb Ron Teitelbaum:
>
> Thanks Tim.
>
> A few questions for everyone.  https://forms.gle/CsEpHvipoGbeud9k8
>
> If you have a minute please take a moment to answer this anonymous survey
> in google forms.
>
> Thank you!
>
> Ron
>
> On Fri, Jul 16, 2021 at 1:14 PM tim Rowledge <tim at rowledge.org> wrote:
>
>>
>>
>> > On 2021-07-16, at 8:49 AM, Ron Teitelbaum <ron at usmedrec.com> wrote:
>> >
>> > Hello everyone,
>> >
>> > Hope everyone is doing well.
>> >
>> > How do we document Squeak?
>>
>> Don't forget the HelpBrowser. There are already some quite good pages in
>> there and there should be a lot more. My suggestion would be that the
>> HelpBrowser should include basic information and guides on how to use stuff
>> - ie the sort of info that really doesn't fit well into class comment
>> organisation - with pointers to more extensive doc on the Swiki.
>>
>> We *could* make it possible to load that Swiki info directly, or we could
>> include the 'start up a web browser on this link' stuff from the
>> ScratchPlugin.
>>
>> Obviously the key issue is getting people to write anything, anything at
>> all, by way of documentation. It doesn't seem to be a popular hobby.
>>
>>
>> tim
>> --
>> tim Rowledge; tim at rowledge.org; http://www.rowledge.org/tim
>> USER ERROR: replace user and press any key to continue.
>>
>>
>>
>>
>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20210717/98ed8b62/attachment.html>


More information about the Squeak-dev mailing list