[Newbies] Smalltalk klass dokumentation ?

[David Mitchell]

> This just is NOT so. Javadoc was and is the brilliant idea to put the
> documentation in the code so that it could be easily updated.

Listen, I'm not disparaging Java nor Javadoc. I've done professional
Smalltalk and Java since 1995. Prior to that, I was a professional
technical writer. I always deliver Javadoc (and I always write class
and method comments in Squeak). The process for *writing* comments is
essentially the same.

> Java has been a great success even though it came later than Smalltalk. One
> key question is - why?
>
> Could lack of good systematic documentation be one of the reasons?

Oh sure, but there are more reasons than just that. Smalltalk isn't
Java. It's different.

Lots of Java open source tools are really underwritten by major
corporations. Very few Smalltalk efforts have such underwriting. When
IBM had hundreds of coders and technical writers working on Smalltalk
rather than Java, the quality and volume of Smalltalk doc was higher.
Cincom Smalltalk still follows this practice (but they aren't open
source). Cincom has outstanding doc (and an amazing library of
videos).

Consider this:

Squeak has a facility for writing comments and hyperlinking them. You
can browse the comments in Squeak.

People have built tools like the javadoc tool for Squeak to extract
the comments and turn them into HTML. Here is the result of someone's
work:
http://www.oldenbuettel.de/squeak-doku/ST80-Paths/Arc.html

Now, that looks a lot like Javadoc!

So now the question is. Other people have built the Javadoc
infrastructure for squeak. But no one took up the cause. Why?

I believe there is a new documentation team forming. You may want to
subscribe to squeak-dev and ask about it.