Documentation can be viewed as both a formal record of outcomes and knowledge, and as a mechanism for communicating these outcomes and knowledge. In both cases, the documentation needs to be comprehensive, precise, and also effective.

The effort required to produce effective documentation can be considerable. We need to consider whether this effort is justified. The simplest way to do this is by looking at what we gain from effective documentation, and what we lose by having ineffective or absent documentation. Effective documentation provides us with a way of ensuring that the process is open and understood and that we understand the process and the results of this process. Documentation provides a record which can be referred to, both to learn from, and more significantly as a bench-marked and accepted milestone in the development. If this is missing then we risk misinterpreting or losing information gained in the process (such as, for example, our own understanding of the requirements of the application being developed) [7].

One of the most successful technique used in object-oriented component design is the object-oriented application framework, but it is a difficult structure to document, especially for its dynamic properties and the inter-component constraints/contracts. A framework is a reusable design of a program or a part of program expressed as a set of classes. Reuse involves an application developer, or team of application developers, customizing the framework to construct one concrete application. Documenting frameworks for developers are very important. Without documentation, developers have to go through codes in the framework to extract necessary information. It is especially difficult for application developers to utilize black-box frameworks if there is no documentation available. Then we will lose the advantages of reuse. The large learning curve faced by the first-time user of a framework is a serious impediment to successfully reaping the benefits of reuse. The design of frameworks is abstract, but frameworks should be easy to understand and customize, which can be realized by documenting frameworks. Documentation of frameworks can present concrete examples to make the framework easy to understand and customize. Success and effectiveness of customizing framework strongly depends on how good the documentation has been made. Guidances from the documentation will definitely save developers a lot of time. For a developer responsible for the maintenance and evolution of a framework, the documentation for the design of the framework is crucial to grasp the application domain, the overall architecture, its rationale, and the reasoning behind the selection of the hot spots [2].

Documenting frameworks also affects other framework issues. It is a costly activity, and it should be considered in the economics of framework development. Documenting frameworks are concurrently carried out with the framework development. The framework documentation should be present before an application developer can use a framework. Without documentation, framework integration will lose its guidance. Documenting black-box framework becomes very important since an increasing percentage of black-box frameworks are being producing.

The objective of this project is to review existing documentation techniques and propose guidelines for documenting frameworks.

From a development point of view, a framework has to be general enough to be useful, but it has to be precise enough to be programmable and to have reasonable performance. From a reuse point of view, we have to document frameworks succinctly, unambiguously, and understandably. The components of the framework should be searchable. In the process of documentation, there are issues related to representing the existing frameworks, their inter-object behaviors, their usages, scalability, extensibility, and searchability [6].

Accurate and comprehensible documentation is crucial to the success of large-scale frameworks. Documenting frameworks must describe the purpose of the framework, how to use the framework, and the detailed design of the framework. The design of the framework fixes certain roles and responsibilities amongst the classes, as well as standard protocols for their collaboration. The variability within the family of applications is factored into hot spots. The framework provides simple mechanisms to customize each hot spot. The documentation should document both general and specific functionalities.

Documenting frameworks is a costly activity and contemporary tools often focus on low-level method-oriented documentation, which fails to capture the strategic roles and collaborations among framework components. With the advent of tools for reverse-engineering the structure of classes and objects in complex frameworks, accuracy and utility of framework documentation will be improved. An increase in the current trend of using design patterns will provide higher-level descriptions of frameworks.

Generally, traditional framework documentation just provides static views of a framework. The static views are very important to understand the basic structures and general functionalities of the frameworks, but it is not enough to represent the whole framework. The run-time architecture of a framework is characterized by an inversion of control. Sometimes, documenting the dynamic side of a framework is more important for framework reuse. Each framework has control flow among the various methods of the framework's classes. Documenting framework behaviors is very critical for application developers to understand the whole structure of the framework. Documenting dynamic views of a framework is more difficult than documenting static views, and it requires more advanced techniques.

For users to document a framework effectively, we need to plan the level and form of the documentation - we need a framework for governing the production of documentation. This framework may be as simple as guidelines (as part of the project plan and/or quality plan) for the production of the documentation and what standards it will adhere to. The guidelines should, as a minimum cover aspects such as: a list of the documents to be produced, expected dates (or as outcomes of certain activities which themselves have specified time frames), formats, content, scope, and responsibilities. Consideration should also be given to configuration management with respect to the documentation (though this is a broader issue which covers all artifacts resulting from the development process).

3.1 Multiple views of a framework

It is important to realize that the framework documentation really addresses different audiences, and sometimes a combination of audiences.

The majority of framework re-users are application developers. Most of them wants to know how to customize the framework rather than how frameworks are designed. Advanced application developers may want to know more about the design in order to reuse the framework efficiently. Framework maintainers must understand the design of the framework. Many aspects of the framework that need to be grasped: the application domain, the overall architecture and its rationale, the reasoning behind the selection of the hot spots, and why the design pattern was selected. It means that we have to provide multiple views of the framework to different users. Some users need more design knowledge than the others do. In the process, different kinds of techniques can be used as needed.

Note that documenting frameworks is a costly activity. Most of the time, it is not practical to provide all possible views for each framework. To provide what kinds of views to audiences is also an activity to deal with in the economics of developing frameworks. It is a trade-off between our objectives and economics.

3.2 Approaches on documentation

Traditionally, documenting frameworks focuses on documentation rather than specification. Various styles of documentation have been used. The source code of example applications that have been constructed using the framework is often the first and only documentation provided to application developers. This style documentation requires a graded set of training examples. Each example should illustrate a single new hot spot, starting with the simplest and the most common form of reuse for that hot spot, and eventually providing a complete coverage of the framework.

The other popular way is to use cookbooks and recipes to document frameworks. A recipe describes how to perform a typical example of reuse during application development. A cookbook is a collection of recipes, and the first recipe acts as an overview for the cookbook. Most cookbooks revolve around a small number of simple example applications. Johnson [3] introduced an informal pattern language that can be used for documenting a framework in a natural language. Patterns provide a format for each recipe, and an organization for the cookbook. The organization follows a spiral approach where recipes for the most frequent forms of reuse are presented early, and where concepts and details are delayed as long as possible.

A design pattern presents a solution to a design problem that might arise in a given context. The description of a design pattern explains the problem and its context, the solution, and a discussion of the consequences of adopting the solution. When an application developer needs a deeper understanding of a recipe, a design pattern illustrates relevant architectural issues. A framework, much like its name implies, provides a reusable design for part of or an entire program. Frameworks are generally more abstract, since they have to be molded to each specific situation that they're used for. A framework is documented with smaller patterns that are used to deal with smaller parts of a larger program. Each pattern builds off the one before it, and by providing patterns with a framework, someone can write a program to deal with something that they might not even understand. Design patterns are especially useful in documenting black-box frameworks.

To reduce the learning curve for application developers, a reuse case [4], which is a use case where the user is a reuser of a framework, describes one well-defined way of reusing a framework. It has name, purpose, roles of the actors, and the scenario. The five categories of reuse cases are composing, extending, flexing, evolving, and mining.

Setting the context of a framework is a first step in helping an application developer reuse a framework. A framework overview is often the first recipe in a cookbook. Reference manual, design notebooks, and other styles of documentation are also useful to document frameworks.

3.3 Approaches on Specification

The specification is a very important document as it describes clients requirements in detail a nd will form the basis for designing the application. The specification forms an important part of any contract document which the developer has with the client. A specification may include (among other things) an overall context for the application, profiles of the users, information requirements, functional requirements, non functional requirements, development requirements, and acceptance criteria. To develop these requirement specifications we will have to carry out activities such as requirements Eli-citation and analysis, implication analysis, user analysis, boundary analysis, content analysis, and constraint analysis.

The specification which results from the analysis activities should cover both the functional requirements and the non functional requirements of the application. Once we have a deeper understanding of the application we will also typically be able to refine the process model, the project management plan, identify resource requirements more suitably and develop a much more accurate cost estimate.

A failure to carry out the analysis activities or to develop an appropriate specification will have a number of significant ramifications. First and foremost a failure to adequately understand and document the requirements of our application will mean that we are developing an application which may be incorrect, inappropriate, unnecessary, or simply irrelevant. Whichever the case, we are likely to end up with an application which is not what we wanted - having wasted considerable time, money, and other resources.

A framework involves the collaboration of several objects. Understanding what a framework does and how it does it requires a description of the interactions between objects. If a documentation does not promote understandability and does not convey the purpose of the behavior, it does not fit the needs of application developers.

A contract is a specification of obligations and collaborations. It provides a specification of the class interface and class invariants, and it also deals with the co-operative behavior of several participants that interact to achieve a joint goal. When a developer needs to consult a specification of collaborative behavior of classes, a contract can support a cookbook recipe with additional rigor.

3.4 Practical Approaches

Even though those approaches have been used for a long time, they are still by far the most basic and useful styles for documenting frameworks. Sometimes one approach can be embedded in another approach. The problem is that each approach only focuses on a particular aspect of the framework documentation. For example, application examples only deal with how to customize hot spots. Each approach is only helpful for a particular group of people. To fully realize the documentation of an application framework, there are number of issues to deal with. In order to realize multiple views of the framework, a combination of all sorts of approaches might be necessary. First, an overview is necessary at the beginning of the documentation. Then we can use patterns to organize the documentation for different components, and divide it into different sections for their corresponding audiences. For general application developers, a cookbook section is suitable, and recipes are included in the cookbook. For advanced application developers, we can use contracts. For each hot spot, we can use examples to show how to customize. We also use cross-references to combine components and sections together.

Documenting frameworks accurately is very critical for the framework reuse. It is especially important for documenting framework behaviors. Concerning the roles of virtual functions play in frameworks, usual approaches just provides the sufficiently general characterization of the functions. The differences between their corresponding methods in derived classes are abstracted away. An approach to document framework behaviors [5] is to specify the behavior of framework as an invariant. In the invariant, specify the relation between the state of a controller object, which provides flow control for other derived objects, and the values returned by various function calls. Application developers plug-in the specific behavior exhibited the same invariant at certain conditions. Then different behaviors will be presented.

The documentation also has to include the dynamic views of the framework. Dynamically complex interaction amongst framework components creates difficulties in their use and adaptation. A framework can be understood very well by visualizing the collaboration and responsibilities of the various components at runtime. Diagram techniques relating to dynamic framework interaction can be used. Especially animation will be a highly recommended technique to do the framework documentation. Other new techniques can be used to support this approach. Hypertext links enable quick navigation between the source code and documentation and keep the two synchronized as source code evolves. Clear and concise developer documentation can be provided online in the now standard Portable Document Format (PDF) from Adobe Systems. PDF allows the developer to view and print system documentation while maintaining the look and layout of an original. Those techniques are very efficient and easy to understand. Clearly they also avoid information redundancy in the documentation.

Documenting black-box frameworks is another very important issue. Design patterns like Bridge and Strategy can describe dynamic object relationships in the frameworks. We can use them to factor out common interfaces and components to simplify the framework documentation. In the documentation, given the name of design patterns used in the frameworks, developers can easily understand what is going on in the framework. In black-box frameworks, objects are too small units of reuse to provide any real leverage. When a set of objects are used together to accomplished a frequently needed task, it is worthwhile packaging them as a unit. The documentation model presented by Mili and Sahraoui [6] contains five descriptive slots: variables, participants, constraints, tasks, and instantiations. It also supports abstraction through a set of closure operations. The dynamic views of the framework are represented through inter-object behavioral composition which is based on notification based mechanism. A packaging operation on frameworks packages a specific instantiation of a framework into a concrete class definition.

Framework documentation is not a free by-product of the development of the framework. Documenting frameworks should be carried out from the very beginning. It is expected to expand effort on creating the documentation. Otherwise, it is very easy to lose important design information in the documentation. Reusable designs result from evolution and iteration. Possible changes for the documentation should be made to be consistent with the current framework in case the framework is modified.

In the process of the framework development, design and framework documentation are strongly coupled. The documentation should be tailored to the scope and level of the application domain. Design is a creative process. For any given set of requirements there will be no single correct solution. For a given specification of an application, different designers will come up with different designs that meet the same specifications. This is similar to designing a house. If we give our requirements to different architects they will come up with different plans for the house. Once the audiences are targeted, the framework documentation should focus on the objectives and analysis requirements. To avoid the framework architecture drift, design should follow the analysis requirements recorded in the documentation. Essential design information should included in the framework documentation, but trivial design information should be hidden from application developers.

1. The documentation should be tailored to the scope and level of the application domain of the framework.

2. Multiple views of the framework should be provided for different audiences.

3. An overview of the framework should be prepared, both as a live presentation and as the first recipe in the cookbook.

4. A set of example applications that have been specifically designed as documentation tools is required. The example should be graded from simple to advanced, and should incrementally introduce one hot spot at a time. A hot spot that is very flexible may need several examples to illustrate its range of variability, from straightforward customization through to elaborate customization. One of the simpler example applications should be used in the overview presentation. The cookbook recipes will use sample source codes from the example applications.

5. A cookbook of recipes should be written, and organized by pattern languages. The recipes should use the example applications to make their discussion concrete. There will be cross-references to any other available documentation.

6. Documenting frameworks costs a lot of time and money, and the money spent on documentation should be appropriate to the whole product.

7. Documenting frameworks should be done from the very beginning of framework development.

8. The documentation should include both low-level method-oriented documentation and high-level descriptions of frameworks.

9. The documentation should have both static views and dynamic views of the framework.

10. The framework should be documented accurately.

11. Avoid information redundancy, and document frameworks simply and effectively. Encapsulate information not useful to application developers.

12. Make possible changes in case frameworks are modified.

13. Use as much advanced software technology as possible to make the documentation easy to understand and customize.

14. Design patterns and inter-object behavioral composition are useful techniques to document black-box frameworks.

When we use those heuristics, we should remember that several trade-offs need to be resolved in the framework documentation. We need to provide multiple views of the framework, but this activity is confined by the budget of the project. A simple documentation is expected in general, but it also needs to provide understandability. In the documentation, we should balance the low-level method-oriented documentation and high-level descriptions well. Once we use those heuristics properly, we can make good framework documentation.

[1] G. Butler and P. Denommee, Documenting frameworks, 1996.

[2] R. E. Johnson, Documenting frameworks using patterns, 1992.

[3] G. Butler, A reuse case perspective on documenting frameworks, 1997.

[4] N. Soundarajan, Documenting framework behavior, 1996.

[5] H. Mili and H. Sahraoui, Describing and using object frameworks, 1997.

[6] C. Lilienthal and W. Strunk, Proceedings of the Tools'96 Conference, St. Barbara, 31.07.-02.08.1996.

[7] ....