Guideline: Developing a Specification for a Reusable Asset
This guideline explains how to develop a Specification for a Reusable Asset.
Relationships
Main Description

Introduction

A project that produces a Reusable Asset needs to capture all the main concerns regarding the problem and the matching solution in an Asset Specification, even for assets that aren't executable software.

Brief Outline

When defining the asset's specification, the following information should be collected:

  • Identify who will consume the asset, and how it will be used.
  • Definition, scope, and type: Determine if the asset is to be a "black box", "gray box" or a "white box" asset. For more information on these concepts, see Concept: Reusable Asset. If the asset is a "white box" asset then generally more of the artifacts are prepared for the asset consumers to work with directly. This can increase the harvesting and packaging costs.
  • Classification and relevant contexts: Determine how the asset will be classified and what contexts for which the asset will be relevant. The asset may be relevant to multiple contexts such as a specific development context and may be relevant to a specific business context as well as a deployment context. The asset's classification generally includes additional information such as the author, the change history, and so on.
  • Potential owners and maintainers of the asset: Never create anything for which there is no plan for it to be maintained.
  • Possible related assets: This is related to asset scope -- what does the asset perform itself, as opposed to requesting services from other assets? Thus, when defining the asset, it is important to identify any assets on which the asset depends.
  • Potential variability points, or customization points
  • Initial usage instructions: Document any significant features and instructions, including any initial rules for using the asset.
  • Side effects of creating the asset: The impact to the development and other activities that could result from reusing the asset should be anticipated.
  • The level of testing that should be performed.
  • Quality-of-service attributes.
  • The level of documentation that should be provided.
  • The asset production approach, will the asset be harvested or developed or acquired?
  • If the asset is to be harvested, any existing project artifacts that may be used as part of the asset.
  • If the asset is to be developed, recommendations on specific artifacts that should be created as part of the asset.

The target user experience for the asset greatly determines the nature and structure of the packaging. Delivering an asset for online browsing and purchasing on the Web will require a different set of documentation than will the asset that is incorporated into the binaries of a development environment. When all is said and done, both user experiences should deliver the content that you are seeking, but the routes to that end point may vary.

The initial asset documentation captured in the asset specification will be refined during the development and/or harvesting of the Asset Artifacts.

Tailoring

The Specification should be adjusted to suit the nature of asset. The elements described in the Brief Outline section are strongly recommend, but additional content may be needed for a specific kind of asset.