Thoughts from an outsider

Ramon Leon ramon.leon at allresnet.com
Wed Aug 30 20:34:07 UTC 2006


> Communities that tell their users to RTFM find themselves 
> alone very quickly. We're telling ours to RTFSC. There has 
> got to be a compromise better than that. 
> 
> --Benjamin

I never said documentation was bad, I was simply responding to the invalid
accusation that the Smalltalk style of self documenting code is wrong, or
that we're copping out or lying made by JJ below...

> And dont go down the road that "smalltalk is simple so the 
> code documents itself".  The code NEVER documents itself, 
> that is a cop-out and a bold face lie.  

And...

> I appreciate the simplicity of the language, but it is because of this 
> reason one must guard against the false feeling of "self documenting 
> code".  

Saying we could use more documentation, is quite different than saying our
practices are wrong, or we are lying, or fooling ourselves with false
feeling of "self documenting code".  

Documents mostly don't exist because there's no one writing them, this is
after all an open source community and the people in the know are too busy
writing code.  

The entire community, I'm sure, is open to accepting any documentation
anyone feels like writing, including JJ.  But in a fast moving development
effort, like Squeak, Seaside, and many other projects I'm sure, there's
always going to be a lack of documentation, that's just life.  

This isn't some big commercial framework where you can point a finger and
say hey, you should have written more documents.  Those kind of documents
will naturally evolve as the frameworks settle down and start being used
more, but don't insult the authors of such frameworks by calling them liars,
seriously, be grateful those guys are writing cool stuff for us to use,
worry about documents later.




More information about the Squeak-dev mailing list