Patterns for Documenting Frameworks

Object-oriented frameworks are a powerful technique for large-scale reuse capable of delivering high levels of design and code reuse. As software systems evolve in complexity, object-oriented frameworks are increasingly becoming more important in many kinds of applications, new domains, and different contexts: industry, academia, and single organizations.

Although frameworks promise higher development productivity, shorter time-to- market, and higher quality, these benefits are gained only over time and require up-front investments. Before being able to use a framework successfully, users usually need to spend a lot of effort on understanding its underlying architecture and design principles, and on learning how to customize it, which together imply a steep learning curve. This effort can be significantly reduced with good documentation and training material.

The pattern language comprises a set of interdependent patterns that aim to help developers and technical writers become aware of the problems that they will typically face when documenting object-oriented frameworks. The patterns were mined from existing literature, lessons learned, and expertise on documenting frameworks.

The pattern language describes a path commonly followed when documenting a framework, although not necessarily from start to end. In fact, many frameworks are not documented as completely as suggested by the patterns, due to different kinds of usage (white-box or black-box) and different balancing of tradeoffs between cost, quality, detail, and complexity. One of the goals of these patterns is to expose such tradeoffs, and to provide practical guidelines on how to balance them to find the best combination of documents for each specific context.

According to the nature of the problems addressed, the patterns are organized in:

• artifact patterns (which kinds of documents to produce? what should they include ? how to relate them?) to which belong the patterns here documented, and

• process patterns strictly related with the process of cost-effectively documenting frameworks (how to do it? which activities, roles and tools are needed?).

As the name suggests, this category of patterns are related with the process of documenting object-oriented frameworks.

Framework documentation is produced mainly during framework development, resulting in user manuals teaching how to use the framework, and design documents to explain how it works and describe its underlying design principles and mechanisms.

Once produced, framework documentation is then used and reviewed during all phases of framework development. It is probably at framework instantiation, during application development, that documentation is used in a more intensive way. It acts as a means of communicating important information from the original framework designers, primarily to framework users, but also to other framework designers and framework maintainers.

The incorporation of comments and feedback from readers is very important for improving the quality of future revisions of the documentation, so it is important to establish an effective bidirectional communication mechanism between documentation authors and readers.

As a framework evolves during the expected long life of the respective framework, the accompanying documentation must evolve as well, and therefore the maintenance of documentation is an activity to be taken in consideration during all framework’s life.

To describe the patterns, we have adopted Christopher Alexander's pattern form: Name-Context-Problem-Solution-Example. We will overview the pattern language by summarizing each pattern’s intent. The following figure shows the relationships between the patterns.

TARGETING AUDIENCES describes one of the first activities in the overall process of documenting a framework, which is to define and prioritize the audiences intended to be addressed by the documentation. Having defined the audiences on target, the contents can be properly created and organized so that they can be presented through the most appropriate views and formats for those audiences.

CREATING DOCUMENTS provides hints on the main activity of documentation. It explains how to streamline the creation of documentation artefacts (documents, models, source code fragments, etc.) both by developers and technical writers, to yield a good quality and cost-effective documentation.

CROSS-REFERENCING CONTENTS addresses the problem of linking and relating different documentation artefacts (e.g. examples, patterns, source code), to provide good navigability between all the contents involved, and therefore to minimize the obstacles to learning strategies that readers spontaneously adopt.

PRESERVE SEMANTIC CONSISTENCY suggests ways of coping with the difficulties of preserving the semantic consistency between related software artefacts (source code, models, and documents) during development to enable their continual review and modification throughout the lifecycle and thus to preserve its accuracy and value for the readers.

ORGANIZING DOCUMENTS provides hints on how to keep all the contents consistent, well structured, integrated, easy to browse, and easy to maintain.

PUBLISHING AND PRESENTING CONTENTS describes the ultimate activity of documentation, the reason why it is produced and organized. The pattern addresses issues on using documentation, not only to read contents in a presentation format, but also to browse, search, select, and navigate through the contents, what sometimes requires processing of contents (transformations, filtering, composition, etc.), to present them in a format convenient for the user.

CHOOSE SUPPORTING TOOLS addresses the problem of ensuring quality and reducing the typically high costs associated with the production and maintenance of framework documentation. The pattern suggests automating the documentation process the best as possible, while retaining the flexibility and adaptability to different developers and environments.

Artifact patterns address problems related to the documentation itself, here seen as an autonomous and tangible product independent of the process used to create it. They provide guidance on choosing the kinds of documents to produce, how to relate them, and what to include there.

Similarly to other technical documentation, the overall quality of framework documentation is complex to determine and assess, and this is perhaps the first issue. Documentation must have quality, that is, it must be easy to find, easy to understand, and easy to use. Task-orientation, organization, accuracy, and visual effectiveness are among all documentation quality attributes, the most difficult ones to achieve on framework documentation.

From the reader’s point of view, the most important issues are providing accurate task-oriented information, well-organized, understandable, and easy to retrieve with search and query facilities. From the writer’s point of view, the key issues are selecting the contents, choosing the best representation for the contents, and organizing the contents adequately, so that the documentation results of good quality, while easy to produce and maintain.

To describe the patterns, we have adopted Christopher Alexander's pattern form: Name-Context-Problem-Solution-Example. We will overview the pattern language by summarizing each pattern’s intent. The following figure shows the relationships between the patterns.

DOCUMENTATION ROADMAP helps on deciding what to include in a first global view of the documentation that can provide readers of different audiences with useful and effective hints on what to read to acquire the knowledge they are looking for.

FRAMEWORK OVERVIEW suggests providing introductory information, in the form of a framework overview, briefly describing the domain, the scope of the framework, and the flexibility offered, because contextual information about the framework is the first kind of information that a framework user needs.

COOKBOOK AND RECIPES describes how to provide readers with information that explains how-to-use the framework to solve specific problems of application development, and how to combine this prescriptive information with small amounts of descriptive information to help users on minimally understanding what they are doing.

GRADED EXAMPLES describes how to provide and organize example applications constructed with the framework and how to cross-reference them with the other kinds of artefacts (cookbooks, patterns, and source code).

CUSTOMIZATION POINTS describes how to provide readers with task-oriented information with more precision and design detail than cookbooks and recipes, so that readers can quickly identify the points of the framework (hot-spots) they need to customize and get a quick understanding about how they are supported (hooks).

DESIGN INTERNALS explains how to provide detailed design information about what can be adapted and how the adaptation is supported, by referring the patterns that are used in its implementation and where they are instantiated.

REFERENCE GUIDE suggests what to include as reference information and how to structure the documentation to make it as complete and detailed as possible. The purpose of the reference guide is to assist advanced users when looking for descriptive information about the artefacts and constructs of the framework.

TRAVERSABLE CODE provides hints on how to organize and present source code, both of the examples and the framework itself, when desired, to make it easy to browse and navigate, from, and to, other software artefacts included in the overall documentation, namely models and documents.

ERROR RECOVERY GUIDE explains how to help users on understanding and fixing the errors they encountered when using the framework.