Pattern: Framework Overview

To be effective, the documentation of a framework must include information that explains the purpose of the framework, how to use it, and how it is designed and implemented.

In addition to different purposes, the documentation of a framework must also meet the needs of different categories of software engineers involved in framework-based application development, playing different roles (framework selectors, application developers, framework developers, framework maintainers, and developers of other frameworks), having varying levels of experience, and therefore requiring different kinds of information.

How to help readers on getting a quick, but precise, first impression of a new framework?

Different audiences. In a first contact, the most important kinds of readers to consider are framework selectors, someone who is responsible for deciding which frameworks to use in a project, and new framework users, developers without previous knowledge or experience with the framework. The first kind of information that a new framework user looks for is contextual information. Framework selectors will look for a short description of the framework's purpose, the domain covered, and an explanation of its most important features, ideally illustrated with examples.

Completeness. The readers appreciate complete information, i.e. that all of the required information is available. Completeness implies that all of the relevant information is covered in enough detail, but only the necessary, and that all the promised information is included. But completeness depends on the reader’s point of view, and therefore requires knowing the audience and the tasks the documentation should support.

Easy-to-understand. Information that is clear, concrete, and written using an appropriate style is usually easy to understand the first time. Clarity (especially conciseness) often conflicts with completeness (especially relevance and too much information), requiring a good knowledge about what readers need to know and when they need to know it. Concrete examples help readers on understanding what they are learning because they map abstract concepts to concrete things, which readers can see or manipulate.

Provide an introductory document, in the form of a framework overview, that describes the domain covered by the framework in a clear way, i.e. the application domain and the range of solutions for which the framework was designed and is applicable.

In addition, a framework overview usually defines the common vocabulary of the problem domain of the framework. It clearly delineates what is covered by the framework and what is not, as well as, what is fixed and what is flexible in the framework.

An effective way of communicating this information consists on presenting the basic vocabulary of the problem domain illustrated with a rich set of concrete application examples.

This information is of great value for potential users specially during the selection phase because it helps them to evaluate the appropriateness of the framework for the application at hands, and thus fundaments the selection, or rejection.

In a framework overview, it is common practice to refer or review examples, from simple to complex ones ( GRADED EXAMPLES), and to refer or include an overview of all the documentation (DOCUMENTATION ROADMAP). A framework overview is often the first recipe in a cookbook (COOKBOOK & RECIPES).

JUnit. The framework overview that accompanies JUnit is represented in the figure below. It was extracted from the document “Frequently Asked Questions (FAQ)”, which, from all the documents delivered with the JUnit’s framework, is the one that most clearly presents the information typical of a framework overview, despite its placement in a FAQ not being evident in a first contact with the documentation.

Although not being a good exemplar of a framework overview, it contains its most basic ingredients (the domain covered, the features, and an overview of the documentation), and thus it reasonably fulfils the requirements of a framework overview.

The biggest problem with the JUnit’s framework overview is that it is not easy to find in a first look at the documentation and is not complete. It is however, easy to understand, what is also very important.

Swing. The framework overview of JFC/Swing is provided in the Sun’s tutorial “Creating a GUI with JFC/Swing”, lesson “Getting Started with Swing“, topic “About the JFC and Swing” (Figure below).

This framework overview clearly describes the domain covered by the JFC/Swing and its main features. Although, the customizations possible with the framework are described textually in the overview, they are not linked to the concrete examples of applications included in the documentation in other lessons of the tutorial, both visual and source code examples.

Being the JFC/Swing framework so well-known, this placement of the overview so deep in the documentation hierarchy, instead at the top, to be easy to find in a first contact with the documentation, is acceptable and possibly even more convenient, considering that only a small minority of readers are expected to need to learn what JFC/Swing is about. What most readers would need to learn is what and how they can customize in JFC/Swing to create the GUI they have in mind.

The contents and organization of this framework overview reflects the importance of knowing well the audience and the tasks more likely to need support from the documentation.

.NET. The overview of the .NET framework is provided in the “Getting Started” document (see figure at DOCUMENTATION ROADMAP), topic “What is the .NET Framework?”. A more detailed technical overview is provided in the “Technology Overview” document (Figure below).

This framework overview briefly describes the purpose of the framework, its application domain and its main components, and refers other documents containing more specific information about the framework.

EMF. The overview document of the Eclipse Modeling Framework (EMF), “Eclipse Modeling Framework Overview”, is another good example (Figure 8). It is very complete and provides a brief presentation of the framework and its key features illustrated with the help of concrete examples.