[Squeak-doc] Roadmap proposal.

[max at nbtsc.org]

A couple of thoughts on the Doc Project:

First, as Matthew points out, the current state of Squeak's documentation is really a "political" (I'd say "cultural") problem, not so much a technical one. I see us maybe getting a bit distracted with all the cool technologies that can be brought to bear on the challenge of having good docs. Technical solutions to cultural problems can only really work to the extent that they are built on a solid grasp of the culture. We're all (to varying extents) newbies on this team, so it behooves us to learn the history, attitudes, and values of the community we're trying to be a useful part of.

Squeak's culture, in my limited experience, is messy but friendly, not so different from other mid-size open source projects. We're smart, well-meaning people, scattered around the world. Some are ideologues, some pragmatists. We all have slightly different visions of what we want, and we collaborate to the extent that these visions overlap.

However, Smalltalk is different from other programming languages in a number of ways, one of which I think is especially pertinent here, which brings me to my second point:

Smalltalk was always intended to be a uniquely user-friendly and readable language, built on a few powerful concepts, with a minimum of arbitrary syntax. I think that the reason the more experienced Squeakers are so lackadaisical about documentation is that well-written Smalltalk IS its own documentation. This is a very good thing!

With this in mind, I think that an important guiding principle for this project should be to teach newcomers to read and understand the code first and foremost. Seen in this light, the tutorials are more than just the tip of the iceberg; they may be a significant fraction of the battle. Once a newbie like myself learns to read code to answer specific questions, and learns to use the IDE tools effectively, the remaining need for documentation is mostly for relatively terse, high-level conceptual descriptions of larger systems like Morphic.

I would be in favor of focusing on the existing class and method comments, to make them as accurate and helpful as possible, before we go building an extensive parallel doc system. This might be harder or less fun, but I'm convinced it will be more useful in the end. I think that, having done that, there will still be a need for a Magic Book, but the scope of it may be reduced considerably. Also, we'll probably produce better documentation for having taken the time to really get familiar with what we're documenting. 


Sent via BlackBerry from T-Mobile