Pattern: Graded Example

Information explaining what a framework can be used for is of great value for potential users, as it helps them to evaluate the appropriateness of the framework for the application at hands, and thus fundaments the selection, or rejection of a framework.

The first usage of a framework is always the hardest one as it may simultaneously involve the learning of the problem domain, the domain covered by the framework, and the range of solutions for which the framework was designed and is applicable. Subsequent usages of a framework can be easier and more complex usages may be required and interesting to illustrate with examples.

How to help readers on evaluating the appropriateness of a framework to his particular application at hands?

How to help readers on getting started fast using a framework both for simple and complex kinds of usage?

Task-orientation. Framework users want practical information illustrating what can be done with the framework, and how-to-use it.

Different Audiences. A framework selector is someone (manager, project leader, developer) who is responsible for deciding which frameworks to use in an application development project. Among other information, framework selectors will look for the domain covered and an explanation of the most important features of the framework. New framework users want to identify, understand and manipulate the flexible features of the framework they need, as quick as possible, without being forced to understand the detail of the whole design, but only its basic architecture (static and dynamic).

Cost-effectiveness. Unfortunately, for many frameworks, the source code of example applications is the first and only documentation provided to framework users, as they can be produced during framework development without extra effort.

Provide a small but representative graded set of training examples to illustrate the framework’s applicability and features, each illustrating a single new way of customization, and eventually all providing complete coverage.

The usage of hypertext links in the source code (TRAVERSABLE CODE) and the availability of executable code are a valuable help for understanding the examples.

Set of examples. A good set of examples can serve as a live catalogue for the basic vocabulary of the problem domain and the key features of the framework, constituting a perfect complement to all other purposes of documentation. A proper selection of examples can be very effective for illustrating the domain covered, how-to-use the framework, and revealing some design internals.

Examples. Examples play a key role in framework documentation as they make a framework more concrete, they help on understanding the flow of control, and are easier to understand than design abstractions, although less general.

The source code of example applications constructed using the framework is often the first documentation provided to application developers. The usage of hypertext links in the source code and the availability of executable code are a valuable help for understanding the examples.

The cost of producing examples to deliver with the framework is usually not high, if well planned, as the examples can also be used to drive the development, to verify the real reusability of the framework, and to help on documenting the framework.

The examples must be used to show what the framework is good for, and not for showing how to use the framework, nor for explaining how the framework is designed.

Because good examples help new users on getting started fast, the study of working examples is a nice and motivating way of learning a framework, and help drive the learning of the framework to the points of most interest to users, thus making the learning more effective.

The documentation of many successful frameworks provides a lot of examples, which make them easier to understand, to use, and to extend. It was observed that the most typical documentation of successful frameworks includes examples that work right “out-of-the-box”. Some examples are: MVC, ET++, and Java Swing.

JUnit. The next figure presents an extract from the article “Test Infected: Programmers Love Writing Tests” that uses and describes an example named MoneyTest provided with JUnit.

Swing. Swing provides a rich set of graded examples, very helpful for both new and experienced users on better evaluating the applicability and feasibility of the framework regarding the specific needs of the application at hands. The next figure shows part of a Swing tutorial fully based on examples.

Providing a good set of graded examples for a framework is usually the less expensive kind of documentation, useful during framework development and testing, and helps both new and experienced users on quickly evaluating what can be done with the framework and also reveals a little about how to use it. Examples are very task-oriented and can thus reach several audiences at the same time but they don’t completely satisfy all of them (e.g. framework maintainers). Despite their value, they are however not sufficient to completely document a framework.

It is useful to include in the examples references to the COOKBOOK AND RECIPES explaining the CUSTOMIZATION POINTS used in the example, optionally referencing information about the DESIGN INTERNALS and also TRAVERSABLE CODE, but this adds an extra need for maintaining the consistency of these references.