[Squeak-doc] Roadmap proposal.

[Matthew Fulmer]

On Thu, Apr 05, 2007 at 07:12:10PM +0000, max at nbtsc.org wrote:
> <snip>
> 
> 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!

This is exactly correct. I could not find a good way to say
this, but I intended to make that point.

> 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. 

This is a very important point, and one I completely overlooked
in my road map proposal. You are absolutely right. Class and
method comments are the best tool currently existing for
documenting Squeak behavior, better than Swiki, Pier, and Sophie
for what they do. Comments have all the critical features we
need for a useful documentation system:
- They fit into packages and can be distributed
- They are integrated into the existing Squeak tool set
- They can be easily searched, modified, and distributed

Ignoring comments would be a fatal mistake to any documentation
effort, and I was in the process of making that mistake. Thank
you Thank you Thank you for calling my bluff.

This observation makes my road map proposal look a lot more
realistic. Comments, rather than some combination of Sophie,
Pier, or something else, should be the ultimate holders of the
document republishing effort that Paul Bennett has begun. We
already have all the tools we need to solve our documentation
problems!

It also greatly simplifies the implementation of the web/image
duality I would like to have. By creating a Magritte Description
for comments, Pier would be able to create an entire book by
stringing together class comments. This book could be viewed
in-image or on the web, and editing any of the three views
(comments, web book, image book) would update the other two.

I cannot believe I overlooked comments in my proposal. Thank you
for reminding me. I will correct this immediately.

-- 
Matthew Fulmer -- http://mtfulmer.wordpress.com/
Help improve Squeak Documentation: http://wiki.squeak.org/squeak/808