Smalltalk MusingsRichard Demers on SmalltalkSmalltalkDoc Use Cases - Creating Component Documentation- April 1, 2006 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...http://www.cincomsmalltalk.com/userblogs/rademers/blogView?showComments=true&printTitl... SmalltalkDoc Use Cases - Creating Overview Documentation- April 1, 2006 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...http://www.cincomsmalltalk.com/userblogs/rademers/blogView?showComments=true&printTitl... SmalltalkDoc Use Cases - Using Patterns- April 1, 2006 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.http://www.cincomsmalltalk.com/userblogs/rademers/blogView?showComments=true&printTitl... SmalltalkDoc Use Cases - Using Frameworks- April 1, 2006 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...http://www.cincomsmalltalk.com/userblogs/rademers/blogView?showComments=true&printTitl... SmalltalkDoc Use Cases - Using Subsystems- April 1, 2006 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...http://www.cincomsmalltalk.com/userblogs/rademers/blogView?showComments=true&printTitl... SmalltalkDoc Use Cases - Using the Class Library- April 1, 2006 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...http://www.cincomsmalltalk.com/userblogs/rademers/blogView?showComments=true&printTitl... SmalltalkDoc Use Cases - New Users- April 1, 2006 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...http://www.cincomsmalltalk.com/userblogs/rademers/blogView?showComments=true&printTitl... SmalltalkDoc Use Cases - Beginners- April 1, 2006 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 CJava 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...http://www.cincomsmalltalk.com/userblogs/rademers/blogView?showComments=true&printTitl... SmalltalkDoc Use Cases - Evaluators- April 1, 2006 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...http://www.cincomsmalltalk.com/userblogs/rademers/blogView?showComments=true&printTitl... SmalltalkDoc Use Cases - Introduction- April 1, 2006 SmalltalkDoc is an on-going project to significantly improve the documentation of the VisualWorks Smalltalk language, components and IDE. It was initiated by Mark Roberts, in the Cincom VisualWorks group. SmalltalkDoc has evolved through two previews shipped with VisualWorks, but these only hint at what is planned. SmalltalkDoc seeks to reduce the burden of producing documentation, to help automate the process of keeping it up to date, and to provide a facility that even experts (being.http://www.cincomsmalltalk.com/userblogs/rademers/blogView?showComments=true&printTitl... |