On the Importance of Doco (Was: Empowering Images)

agree at carltonfields.com agree at carltonfields.com
Tue Feb 22 18:07:03 UTC 2000


> PS. I don't think that anyone seriously wants SqC to stop > development to
> document the system instead.

I dissent!  

While I do not expect SqC to do anything off-task, and recognize that ultimately they are following their research goals, with OSS contribution being a secondary byproduct of what they do, and while I am grateful for all they have done, I for one can say, "YES, I believe that it would be an excellent goal for all contributions, for which SqC is a major source, to be well documented, whether before the fact or after the fact."

Particularly with respect to the most obscure features in Squeak, no one else is as well qualified to produce good, at least preliminary, documentation.  Sure, let others polish, wordsmith and refine the words, but the primal source "stuff" of documentation really ought to pour from the minds of the creators.  Many willing contributors are not yet schooled enough to read through the browsers to induce what these classes actually do, but they would be able to effectively measure and refine a rough sketch.

*THAT'S* how things can get done.  If you look at corresponding projects, such as Python, Guido wrote kick-a** documentation at all stages through the development of the project.  Once it existed, it was easy for others to develop, keep current and maintain.  But first, it had to exist.

Was it a good thing for Python to have Guido spend so much of his energies doing non-development "doc-ing?"  I think so.  I don't know if it made any difference in the development, but it helped a community to rally around the language, and that certainly helped in the development.

That being said, SqC does pretty damned well at virtually everything they do, including documentation.  

So, I am not complaining -- but I am not willing to sign off on the broader statement set forth above.  We ALL need to do the documentation, and if it were my druthers, I would presume to admonish folks that it is never a bad thing to document code, even if it does hold up development somewhat.

BTW, I am shortly going to be putting out an new rev of Squeak Smalltalk: A Quick Reference, at http://www.gate.net/~werdna/squeak-qref.html.  I am grateful to all who have offered comments and editorial suggestions, virtually all of which will be incorporated in the revision.  I would be likewise grateful to anyone who could take the time to review it in the next week or so and proffer their comments regarding the same.





More information about the Squeak-dev mailing list