1.2 Framework Artifacts
As mentioned before, one of the greatest challenges is realizing that most of the framework artifacts must be delivered to the customer. As when developing other software, it is sufficient to document only those places where the customer is likely to work with the software. The difference is that for other software this usually occurs at a few well-defined interfaces. For a framework, the customer works with almost all aspects of the software. The customer needs to understand the requirements, use cases, analysis model, design model, design decisions, programming model, patterns used, and so on. You may even provide the source code to the customer. Suddenly all of these things that were hidden (or not formally produced) in the past are part of your product. The key is realizing that you are a partner with the framework users. You are partnering together to help them develop and deliver their application, and you need to do whatever you can to make them successful.
In addition to the development-level artifacts, a number of other documents need to be considered: documents that help different audiences understand and use the framework. One that we have found extremely important is a document that helps a nontechnical domain expert understand the capabilities of the framework. For example, domain-level user guides should use the terminology that domain experts in the field use, not the technical terms used by developers.
This documentation might also take the form of usage samples, showing how to complete the framework (by using the extension points) to solve specific application requirements. These examples need to work properly so they can be used as a starting point to help framework users understand the framework and then adjust it to their particular needs.
Tooling should also be considered. These tools can range from development tools that help generate code to wizards that help create the framework extensions to support a particular framework user's needs.
Determining the exact artifacts to provide with your framework involves a number of factors (see the Exposing It All pattern, Section 3.6), not the least of which is the time allotted to developing the framework. The important thing to realize is that there will be more artifacts than with other software.