Pattern: Cookbook & Recipes

The quality of information explaining how-to-use the framework is very important to achieve its effective reuse. In most of the cases, the informal communication channels between framework developers and framework users are not available anymore, and, as a result, all information has to be communicated in alternative ways, with different kinds of manuals delivered with the framework, possibly using different media (documents, animations, videos).

To help application developers being effective on the reuse of a framework, ideally, the documentation should be organized in a way that can help readers quickly locate the explanations they strictly need to learn how to use the framework parts required to implement the specific features of the application at hands.

How to quickly provide users with information that helps them on using the framework?

Task-orientation. Readers want to learn how to use the framework, so the documentation must focus on real tasks that users really want to perform, instead of artificial tasks, imposed by the framework.

Balancing Prescriptive and Descriptive information. To be effective, the documentation must achieve a perfect balance between the level of detail of the instructions provided to guide the usage of the framework, and the level of detail and focus used to communicate how the framework works, i.e. its design internals. This perfect balance may vary with the reader of the documentation, and thus the “one size fits all” solution doesn’t work here.

Different Audiences. Readers of different audiences have different needs and interests that must be addressed by the documentation. 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 views). More advanced users may want to learn how to do less common customizations that possibly require a more detailed understanding of the framework’s internal design.

Completeness. Readers appreciate complete information, i.e., that all possible customizations are mentioned, with all the possible detail, but this is not always feasible, as it largely depends on the reader’s point of view and the tasks to support.

Easy-to-use. The resulting documentation must be easy to use, otherwise readers would need to spend more time than needed to browse it, and can get lost on it.

Cost-effectiveness. Unfortunately, many frameworks are very complex to use and understand resulting hard, tedious and expensive to document in detail.

Provide a collection of recipes, one for each framework customization, organized in a cookbook, which acts as a guide to the contents of all its recipes.

Cookbook. A good cookbook is specific to a particular framework. Users search the cookbook for the recipe that is most appropriate for their needs, and when found, they follow the steps it describes. Recipes in a cookbook are usually organized in a spiral approach, where the most common forms of reuse are presented early, and concepts and details are delayed as long as possible. A framework overview is often the first recipe in a cookbook, being responsible for presenting the framework.

Recipe. A recipe is a document that describes how to use the framework to solve a specific problem of application development [6]. Recipes typically present information in natural language, perhaps illustrated with some pictures and code fragments. Although recipes are rather informal documents, they are usually structured in:

• a purpose section, which describes the problem the recipe is meant to solve plus some of the limitations of the solution;
• a procedure section, or how to do section, containing a sequence of the basic steps necessary to carry out the solution, and
• an examples section containing explicit, or implicit, references to models, examples and fragments of source code, and also to other related recipes.

The most important kind of information provided by cookbooks and recipes is prescriptive information that instructs users on how to use and customize the flexibility features provided by the framework. In addition, they also informally describe architectural constructs and design details, but only in a very small amount, the strictly needed to help users minimally understand what they are doing.

The best kind of documentation for beginners seems to be one that provides detailed instructions for using each individual feature of the framework without describing in detail all the theory behind them. Considering that the main purpose of a framework is to reuse design, if it is well designed, then there must be large parts of its design that are easy to reuse even without knowing them.

On the other hand, to start using a framework without having a clear understanding of it seems to be wrong at first, but the fact is that people can’t understand well a framework until they have really used it. The effective understanding of a framework thus requires that theory follows practice [8]. After the first use, the framework user has a much better understanding of what the framework does and is more capable to understand how it works, i.e. to understand its internal design details.

Active cookbook. The active cookbook is a specialization of the cookbook concept that provides active guidance to framework users. Active cookbooks extend the cookbook idea with a hypertext representation, a visual development environment and supporting tools. The tool support provided by active cookbooks helps the user navigate the steps of the recipes and provide the tools needed in each step, thus increasing the productivity.

Johnson’s patterns. Johnson documented the HotDraw framework using a pattern language comprising a set of patterns, one pattern for each recurrent problem of using the framework. The pattern language organizes the documentation, as a cookbook does with the recipes, and each pattern provides a format for each recipe.

To avoid confusion with design patterns, the term motif was later introduced in to name Johnson’s patterns. The description of a motif has sections similar to a recipe, except that use additional references to design patterns, to provide information about the internal architecture, and references to contracts for a more rigorous description of the collaborations relevant to the motif.

Hook description. Hook descriptions were first introduced in and present knowledge about framework usage, providing an alternative view to design documentation. Hook descriptions provide solutions to very well-defined problems. They detail how and where a design can be changed: what is required, the constraints to follow, and effects that the hook will impose, such as configuration constraints. A hook description usually consists of a name, the problem the hook is intended to solve, the type of adaptation used, the parts of the framework affected by the hook, other hooks required to use this hook, the participants in the hook, constraints, and comments. Hooks can be organized by hot spot: a hot spot tends to have several hooks within it. The usage of hooks can be semi-automated.

Cookbooks and recipes were historically the first technique used to document frameworks, namely the MVC framework and the MacApp framework.

JUnit. The next figure presents a recipe for writing a simple test with JUnit, the first of the five recipes contained in the cookbook provided with JUnit, the “JUnit Cookbook” document.

Swing. The Sun’s JFC/Swing framework contains several recipes organized in several cookbooks. The next figure shows the cookbook related with layout managers, which contains a set of recipes explaining how to use layout managers. The ladder figure shows a specific recipe explaining how to use a BorderLayout manager.

Providing a cookbook and recipes for a framework helps on improving its task- orientation, usability, and on combining prescriptive with descriptive information.

The main audience targeted by cookbook and recipes are framework users, i.e., developers of applications intending to reuse the framework as part of it. Due to its user-orientation, this kind of documentation is usually easy to use and understand, but not complete, i.e. it doesn’t intend to cover all the possible customizations with the framework but only the most relevant for the audience on target.

Because cookbook and recipes focus on teaching how-to-use a framework, it is useful to combine them with concrete or running examples, and references to the related CUSTOMIZATION POINTS and TRAVERSABLE CODE, thus adding some redundancy, which although useful must be managed to preserve its consistency.