Smalltalk Musings

Users: Smalltalk developers.

Problem: The Smalltalk domain model consists of both packaging components (bundles and packages) and code components (classes, methods, variables, etc.). SmalltalkDoc defines documents tailored for all of these components. The user needs to be able to identify a component and be presented with an appropriate tool for viewing and editing its documentation.

Solution: SmalltalkDoc provides a code tool for documenting the component currently selected by the System Refactoring Browser. To the extent possible, the documentation tool acquires information from the selected Smalltalk object.

Users: Technical writers with Smalltalk experience.

Problem: Smalltalk IDEs provide ways to attach comments to some objects but not all. Comments are simply plain text strings and they cannot be cross-linked as hypertext. No guidelines are provided to make these comments truely useful to different audiences.

Solution: SmalltalkDoc provides for more comprehensive and integrated documentation. Comments are XML, which may contain formatting, cross-links, and the possibility of code expressions. SmalltalkDoc reifies documentation in a way that helps developers write useful documentation with less effort. Automated code checks can catch common problems, such as class comments becoming outdated when instance variables are added or removed.

Users: Programmers developing Smalltalk applications.

Using Patterns

Problem: Numerous books of design patterns have been published, many of which are of use to Smalltalk programmers; many more patterns exist implicitly in Smalltalk system and application code. The published patterns can be referenced in other documentation, thereby giving follow-on programmers a starting place for understanding an application. The implicit patterns, however, can only be learned through code studies, and lacking an identity and separate documentation, it is not possible for other applications to reference them.

Solution: SmalltalkDoc overview documents can be used to centrally document and organize patterns of general interest to the Smalltalk community. It may also be desirable to define a new type of SmalltalkDoc, a PatternDoc, that provides a common template for the description of patterns; perhaps similar to that used by the original Design Patterns book.

Users: Programmers developing Smalltalk applications.

Problem: Frameworks are often difficult to use. The factoring of complex Smalltalk programs leads to a hierarchy of classes that becomes a framework for the creation of subclasses specialized to meet additional requirements. Over time Smalltalk systems acquire a variety of frameworks that are reusable if someone takes the trouble to identify and document them. This is usually not the case. People who learn of them must study the entire class hierarchy of the framework in order to create further specializations.

Solution: SmalltalkDoc supports the documentation of frameworks through overview documents and through documents associated with bundles and packages. Figures illustrating the conceptual structure of a framework can be included, along with explanations. The overview documents can describe structural relationships that span the packaging components.

Users: Programmers developing Smalltalk applications.

Problem: The APIs of Smalltalk subsystems are often not obvious without considerable study. Developers complain of having to spend hours reading and studying code before being able to use existing subsystems. The problem is that the basic components of Smalltalk code (classes, methods, etc.) do nothing to identify a subsystem's API. Intention revealing names help, but are not sufficient. Explicit API documentation is needed, including both text and illustrations, that provides a framework for thinking about a subsystem and how it is intended to be used.

Solution: SmalltalkDoc supports the documentation of subsystem APIs through overview documents and through documents associated with bundles and packages. Figures illustrating the use of a subsystem can be included, along with explanations.

Users: Programmers developing Smalltalk applications.

Problem: The Smalltalk library contains a wide variety of classes of general use to programmers, each defining a set of generally useful methods. However, it is difficult for programmers to learn and remember all of them. In VisualWorks, moreoever, there is no set convention for distinguishing public from private methods. Programmers usually have to spend time browsing code to determine which classes and methods are already available and applicable to their problem. There was formerly an "Object Reference" Guide to the VisualWorks class library that helped to simplify this task, but this has not been maintained in over ten years.

Solution: SmalltalkDoc supports documentation for all levels of Smalltalk components, including individual methods. However, it would probably not be useful to create SmalltalkDocs for every method of every class, it would be useful to do so for the generally useful common classes, such as Strings, Numbers, collections, or, for example, the Pollock objects (Panes, Agents, etc) that programmers normally work with. More important are the overview documents for code components that point developers towards the most important classes and APIs defined within.

Users: Programmers doing their first projects in Smalltalk. These people have gone beyond the need for tutorials, but they are often overwhelmed by the size and complexity of the class library. They also need guidance in adopting best practices.

Problem: Today, this need is partially met by a set of PDF "Guide" documents, which are not, however, directly available in the Smalltalk environment. The files containing these guides must be located, the correct guide selected and opened, and then searched for the required text. While these guides are indexed and searchable, they do not and cannot provide hypertext links to more detailed Smalltalk packaging and component documentation.

Solution: Existing guide documents can be broken into topical pieces and incorporated as overview documents into an on-line set of SmalltalkDoc documents that are immediately available in the Smalltalk environment.

Users: Programmers learning the Smalltalk language. These people have varying levels of expertise in programming, object-orientation, systems design and systems development. In many cases they are more expert in the C/Java languages.

Problem: People new to Smalltalk first need step-by-step tutorials in the syntax, basic object classes, and messages used for control structures. They also need to learn how to think in terms of interacting objects.

Solution: SmalltalkDoc includes documents in which tutorials can be provided. SmalltalkDocs can link to each other, to SmalltalkDocs at both the packaging and component levels of detail, and to other Internet resources. It may be desirable to define a new type of SmalltalkDoc, a TutorialDoc, that supports the evaluation of Smalltalk code similar to workspaces.

Users: Programmers evaluating Smalltalk for future programming projects. These people have varying levels of expertise in programming, object-orientation, systems design and systems development. They have heard varying claims about Smalltalk and want to check it out for themselves.

Problem: Many people have heard of Smalltalk and its claims of enhanced productivity, and would like to take a quick look at something more detailed than marketing brochures but less detailed than Smalltalk code 14 preferably online and at varying levels of detail.

Solution: SmalltalkDoc provides a great deal of information about Smalltalk. An evaluator can begin by browsing high-level overview documents, sample the tutorial documents, and delve into Smalltalk details with component documents. Evaluators can get fast answers to questions such as: "Does Smalltalk provide support for my favorite database and security protocol?"