> 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. _______________________________________________ Beginners mailing list Beginners@lists.squeakfoundation.org http://lists.squeakfoundation.org/mailman/listinfo/beginners