> On Aug 17, 2018, at 3:42 PM, Ken Causey <klcausey at gmail.com> wrote:
> 
>> On 8/17/2018 4:40 PM, tim Rowledge wrote:
>> 
>>> On 17-08-2018, at 1:19 PM, Keith <keithy at consultant.com> wrote:
>>> 
>>> Hi,
>>> 
>>> where do we put documentation these days?
> 
> While we are on this subject has anyone looked into adding documentation at the category and/or package level? As someone who is barely paying attention anymore but occasionally gets an itch to do some work in Squeak it is really difficult to figure out what is already on hand in an image at a high level, higher than per-class.

+1

> 
>>> Excellent question. Several answers -
>>> 
>>> A method ought to be commented as to what it is *meant* to do. That is not always what the code actually does, for example during early stages of development. It would be nice if the comment explained any known limitations or likely error conditions.
>>> 
>>> A class should be commented to explain its intent, along with what ivars are used for and maybe even the sources for any interesting algorithms used. Mentioning other related classes and how they help might be nice.
>>> 
>>> Add a page to the HelpBrowser system. Take a look at the Help browser (main menu -> Help) and look at the 'Help on Help' section, in particular the 'Implementation' part. This is a good way to document something about systems and applications rather than the classes and code implementing them. We need a *lot* more help pages.
>>> 
>>> Add a page or ten to the swiki. This is a good place to be more expansive since it doesn't take any space in the image or sources. And you can include pictures which we don't seem to be able to do in the HelpBrowser (yet).
>>> 
>>> 
>>> tim
>>> --
>>> tim Rowledge; tim at rowledge.org; http://www.rowledge.org/tim
>>> Oxymorons: Clearly misunderstood
>>> 
>>> 
>>> 
> 
>