View this PageEdit this PageAttachments to this PageHistory of this PageHomeRecent ChangesSearch the SwikiHelp Guide
Hotspots: Admin Pages | Turn-in Site |
Current Links: Cases Final Project Summer 2007

BookWhining

Meant to be a partner to the SqWhining page.

Lots of comments (in diaries, in comments in book) are complaining about the "documentation" of Squeak. Are these complaints about the book? If so, I'd love to hear them! Please do let me know of issues with the book. Leaving comments here anonymously is welcome – I'd rather hear the complaints anonymously than not hear them! Thanks! – Mark Guzdial

The most significant problem with the book is the lack of an index. Other than that, it's fine, for what it is. We want an API book, though. It's too hard to find classes and methods to do what you want, and, once you do, the lack of adequate commenting makes it too hard to figure out how to use them. Any difficulty associated with programming should be derived from complex logic, not from simple documentation.

I know you said that there's no API because Squeak is constantly changing, but that doesn't really make sense. Even if an API book didn't contain information on all the newest classes and methods, it could still have detailed information on the most useful classes and methods in existence at the time of the writing. This functionality would have to be maintained to ensure backwards compatibility, so the book would always be accurate, even if not up to date.

I couldn't even find a web tutorial thta covered more than the absolute fundamentals, much less a book like the API documentation you can find for Java or the standard C/C++ libraries. I suspect that the real reason that no such books exist for Squeak is that there just isn't a sufficiently large market for them.
Brandon Berg

The lack of an index is very annoying. Also, with regards to an API, if everyone's worried about it being accurate, at least a reference to the standard downloadble version would help. David Jaggie

Jess and I just noticed that the CRCCardMorph doesn't support duplication or cut and paste – most Morph things let you click on the "duplicate" button and get another one, but in this case they throw an
"UndefinedObjects are not indexable" error.
Peter Jensen and jess[ica] a. close

I think a rather nice solution would be a class in Squeak that would generate an API for the system, which at the very least would include an index of all the classes and methods in the system organizer. This doesn't seem like it would be all that hard, and the best part is that you would know that the api generated would be accurate if you had it generate based on the changes set you were using. Just a thought.
Shaggz Mickley

http://guzdial.cc.gatech.edu:8080/api.1
if only it were full of stuff..
Jeff Kwasha

Seriously though, Squeak should at least carry a good set of example methods and class comments in the classes that people Need to use a lot. I know I had trouble, and then there was the really wierd stuff that everyone posted about in the milestones...
I tried to document some of that in (shameless plug)
A Small Squeak Tutorial

Mark!
A general well-done on the book, but the one thing that constantly irks me is the fact that there's no index! And you seem to have tried to make up for that by making the toc a bit kludgy. When I need something specific, I find myself going to the Smalltalk-80 book (which, btw, I like quite a bit).
However, I think it would be much more convenient if I could just look in the index of the real book and find what I need.
That's really my only complaint. :)

Thanks. I'm working on the index, but first, I have to finish the OTHER Squeak book (http://coweb.cc.gatech.edu/squeakbook/ – I'm just editor, not writer there). I plan to index the book while I revise the existing 7 chapters (before writing the last four). Mark Guzdial

Links to this Page