Hi all,

At the moment I'm more worried about the contents than the form. Without
contents even a perfect form is empty.

I keep notes about every difficult method I come across (I'd forget
otherwise). Placing detailed notes directly in methods doesn't feel
right - it may (1) clutter the methods (2) create long chains of
versions when updating the comments frequently. My idea - at least
before a better form is available - would be to agree on using
"documentation" class methods for each method to keep such extended
comments, e.g. #docContextEnsure: under the Context class, which would
allow (potentially) frequent updates without affecting the methods
themselves. It would also not discourage one from writing the comments
because deleting comments wouldn't leave a trace in the methods history.

Also, if in the future someone created an intelligent Help system based
on whichever technology (AI, DB, Help, Swiki) it would be easy to access
the contents of the documentation methods or simply delete them all to
cleanup the system.

I can see one potential problem though - access rights to save to Trunk.
Anytime I create or update a comment, who's going to save it to the
Trunk...

About AI: I personally very much like consulting with ChatGPT about
mainstream topics like OOP, FP etc because it has a vast knowledge base
available. Of course the information provided is often inaccurate and
controversial, sometimes I even make the chat bot reverse its "opinion"
by 180 degrees but that shouldn't be surprising, I made the same
experience with human teachers too :)) Unlike humans, however, the bot
is always open for discussion and "willing" to consider my arguments,
clever or stupid, and correct its "opinion" if necessary ;)

(To avoid confusion: By no means I suggest using AI to replace a
teacher; but it's good as a sparring partner with a vast knowledge base;
IMO it's like talking Wikipedia++ with some inference capabilities - can
you trust it? Not really. Is it good to have? For sure.)

However, I have no opinion whether it's even feasible to feed ChatGPT
with the existing (probably limited) Smalltalk data to be able to
discuss at least on a similar level as e.g. in case of Python or Scala.

But back to Earth, before someone volunteers to spend hundreds (if not
thousands) of hours on an intelligent help system, I'd like to start
with simple steps like writing more detailed comments with examples to
methods. Do you think "documentation" class methods is a way forward? At
least as an interim solution?

> (Tim) A method comment should explain what the method is for, and
ought to mention any known limitations or problems, should reference any
standards or papers relating to it, etc. Comments within the code should
help elucidate what the code is *meant* to be doing. Yes, code tells you
what it does; it does not tell you what was intended. I promise you, the
two often diverge significantly.

> (Eliot) Things that would be powerful to have in-image would be:

- being able to find the Monticello package commits corresponding to the
current and previous versions of a method
- being able to find message threads on squeak-dev et al referring to
specific methods, packages, and commits
- being able to find the help topic(s) that mention a specific method,
selector, etc

.... can't agree more!

Thanks,
Jaromir



On 27-Jan-24 12:29:21 AM, "Tim Rowledge" <tim@rowledge.org> wrote:

>
>>
>> I concur that HelpTopic creation by hand is fatally iniffecient and painful, however, it can be generated programmaticaly, which I do in Doc...a naive attempt to solve this problem.
>>
>
>You cannot auto-generate sensible documentation. Simply gathering up class and/or method comments is virtually useless, unless by chance those comments are very well written. Which in general is not the case.
>
>And even then it would be quite important to have the method comments arranged in some order that helps make narrative sense.
>
>And even then, class comments should be about the class (duh!) and that leaves out the whole question of *system* documentation. Which is much more important because that is where the functioning of the group(s) of classes gets explained, and without that explanation you are in real trouble.
>
>A method comment should explain what the method is for, and ought to mention any known limitations or problems, should reference any standards or papers relating to it, etc. Comments within the code should help elucidate what the code is *meant* to be doing. Yes, code tells you what it does; it does not tell you what was intended. I promise you, the two often diverge significantly. Consider the careful comments in LargePositiveInteger>>#digitMul33: etc.
>
>A class comment should give some outline of what the class is about so yo can quickly get a higher level idea. It should mention any known algorithms introduced or papers the ideas are based on so that debugging and improving can be done more effectively. People might need to work out what is going on 25 years later!
>
>Somewhere, there has to be documentation about bigger things; how to connect to & use a database, how to use the morphs for XX, how to handle code management, dealing with bugs, etc etc. That is a very good thing it have in the HelpBrowser world, and probably *also* the swiki. We do have ways to read swiki pages into the Help browsers but I suspect it could be improved a lot, as indeed could the swiki content.
>
>The HelpBrowser seems to be a decent tool these days; you can edit pages, add new ones and so forth. The hard part of creating documentation is not the tools - even using ancient junk like vi can be survived - but working out what to say, making it make sense, making is decently complete, keeping it up to date. Good tutorial type content is important too, and that can be a real pain to keep up to date.
>
>
>> I also agree that AI should do this. Alas, I do not have the bandwidth to learn ai.
>
>I really wouldn't consider any current AI to be any good for this. You'll get the Boris Johnson version, blather and gibberish that looks good for a few moments until you spot something you do already know about and that it has made an utter hash of.
>
>
>> However, what are the steps to building an indexing database? ( I am thinking Postgres here..)
>
>I doubt postgreSQL is appropriate here, fine DB though it is. For a start, it's not in the image if it's in a DB. One might consider Magma if you really need to keep info outside the image. One might consider sets of imagesegments as away of keeping help pages or books; they load very fast.
>
>Strings in-image would surely be the fastest thing to search, especially with clever indexing algorithms. Yes, it would increase the size of the image, maybe by a lot - but for a development image where you want tools and support, why would that be a problem? Does it really matter if a full-fat Squeak developer image is several gigabytes in size? Take a look at how big the packages for some very minor tools are these days. For comparison, some work related Squeak images with seaside, refactoring browser, postgresql, sixx, a whole raft of specific code & data, and still with EToys & the games etc, is 130Mb. When running it has never gone past 200Mb working set. I could run 30 or more simultaneously on a Pi without using any virtual memory. Pfui!
>
>tim
>--
>tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim
>Never trust a computer you can't lift.
>
>
>