On 25-Sep-06, at 5:18 AM, Lex Spoon wrote:
[snip]
>
> Thus, forgive me if I think people may be misunderstanding what is
> already available.  Writing up a bunch of HTML documenting individual
> methods and classes does not make sense for Squeak.
>
> Instead, it makes sense to concentrate on two other areas:
>
>   1. Improving Squeak's own self-documentation.  Many methods
>   and classes are not documented.

Exactly; in-code documentation needs lots of work

>
>   2. Write articles with broader scope.  If you want to know what
>   the methods of Canvas are, then look in your image.  If you want to
>   know how Canvas fits into the Morphic architecture, then you need
>   to read a broader article about Morphic (e.g., the chapter in the
>   "nu-blue" book).

...and don't forget an article/tutorial on using the tools so that  
new users are able to look in the image for the improved class  
comments. Teaching about effective use of the tools is almost as  
important as providing a good basis for understanding  objects and  
messages.

What will almost certainly happen as you write such a tutorial is  
that you will find assorted logical or work-flow problems with the  
tools, which we can then fix. Hopefully. I think of this as   
'Documentation Driven Design' - if you can't write a simple and  
comprehensible explanation then there is  a good chance your app  
doesn't work the way it should.

tim
--
tim Rowledge; tim at rowledge.org; http://www.rowledge.org/tim
Strange OpCodes: CPM: Change Programmer's Mind