Documentation project (was: Thoughts from an outsider)
tim Rowledge
tim at rowledge.org
Tue Sep 5 20:20:18 UTC 2006
On 5-Sep-06, at 1:06 PM, J J wrote:
> I relize there is a possibility to write a book on all this and
> maybe get rich, but I would
> rather write the book for free, make smalltalk more well known/
> lucrative and then
> write 10 books to get rich off of. :)
We-ell, writing a book on squeak doesn't seem to be a particularly
good way to get rich. Been there (at least in part, a group of us
collaboratively wrote the 'nu-blu' book) got the $200 cheque.... I
had much more success getting rich writing Smalltalk than writing
about Smalltalk.
The key problem with any sort of traditional doc for a system like
Squeak is that by the time you have written the outline it is so out
of date that you have no chance of ever catching up. This is why I'd
like to see some sort of image based doc-tool; at least it would have
some hope of being up to date. I *don't* think that merely
aggregating class and method comments is anywhere near enough. Nor
do I know exactly what *would* be enough, sadly. I am pretty sure
that it needs to combine a way of presenting the raison d'être of the
code, the reasoning behind the design, the known limits and tradeoffs
and invariants expected and the tests, examples, demos and even the
method and class commentary.
tim
--
tim Rowledge; tim at rowledge.org; http://www.rowledge.org/tim
Strange OpCodes: HSJ: Hop, Skip and Jump
More information about the Squeak-dev
mailing list
|