LiterateSqueaking

=== Top of the Swiki === Attachments ===

LiterateSqueaking

The Squeak community agrees that Squeak badly needs improved documentation. There are no Squeak specific books, and few instructions. Squeak is fast changing, so hardcopy documents will likely grow obsolete fairly fast.

This is a very important, and neglected, area of Squeak development. It may be the most vital thing to PromoteSqueak

Most proposed solutions involve documenting Squeak within Squeak, using what are, basically, program comments on steroids.

Some such systems have been invented and analysed for other languages, by other people.

A seminal thinker in this area is Donald E. Knuth, Professor Emeritus of The Art of Computer Programming at Stanford University. He promotes a discipline called Literate Programming. LiterateSqueaking is Squeak specific Literate Programming.

Literate Programming has two key ideas:

1) Regard a program as a communication to human beings, instead of as a set of instructions to a computer.

2) View your program as a hypertext document, rather like the World Wide Web.

Literate Programming Links:

Knuth's page: http://www-cs-staff.stanford.edu/~knuth/lp.html
CWEB System of Structured Documentation: http://www-cs-staff.stanford.edu/~knuth/cweb.html
Yahoo: http://www.yahoo.com/Computers_and_Internet/Programming_Languages/Literate_Programming
WikiWikiWeb source: http://c2.com/cgi/wikibase

The Oberon programming-language/operating-system implements some of these ideas in a way highly useful to Oberon newbies. Try it. It shows what Squeak can be:

ETH Zurich: Oberon Homepage: (http://www.oberon.ethz.ch/oberon)
Oberon Reference Site: (http://www.math.tau.ac.il/~laden/Oberon.html)
Introduction to Oberon: http://www.ics.uci.edu/~oberon/

The Eiffel programming language uses a concept called Design by Contract.

http://www.eiffel.com/doc/manuals/technology/contract

Some Squeak Wiki pages discuss such Active Media.

SourceCommentsAsUserInterface clearly states the issues.

DanIngalls promises to enliven Squeak documentation with HypertextClassComments. This is a first step toward ActiveEssays about all aspects of Squeak.

See PaulFernhout's page on StoryHarp, and let your imagination run wild. Think of the possibilities for teaching programming, Smalltalks and Squeak!

Participative-Collaborative Media:

WardCunningham launched this WikiWikiWeb site as interim collaborative media for the growing Squeak community.

Another (Scheme enhanced) SmartWiki for public joint editing literate programs is: (http://baked.vegetable.org:4999/cgi/wikie/show_page?Page=top) -- fp