> On 17-08-2018, at 1:19 PM, Keith <keithy at consultant.com> wrote:
> 
> Hi,
> 
> where do we put documentation these days?

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