Guideline: Documenting Reusable Assets
This guideline provides recommendations on what information should be captured when documenting Reusable Assets.
Relationships
Main Description

Introduction

This guideline provides recommendations on what information should be captured when documenting Artifact: Reusable Asset.

External vs Internal Documentation

The kind of documentation that is developed for an asset, and its level of detail, depends on the the target audience and the target user experience. For example, for an online browsing experience of an asset repository or catalog, the documentation may be less technical. The goal of the documentation for this environment should give the asset consumer enough information to decide to proceed with further evaluation and usage.

There are two categories of documentation when documenting an asset:

  • External asset documentation: The documentation available to asset consumers when browsing an asset repository or catalog where the asset is published. This can be considered marketing material.
  • Internal asset documentation: The documentation that an asset consumer would use to install and use the asset.  This can be considered the asset's user's guide.

The external documentation may be created by abstracting from the detailed internal asset documentation. Some may question the value in taking the time to develop separate, more abstract external documentation that is separate from the internal asset documentation. However, providing a less detailed description of the asset allows asset consumers to get a feel for the purpose and intent of the asset without having to wade through all of the details.

For example: For a very detailed reference application, most people browsing on the Web will not want to spend the time and/or the energy to read the entire Software Architecture Document online. Rather, they would like to have a summary of the architecture. Thus, the recommendation is to put the less technical, more abstract information online (in the external documentation, referred to above) and the more detailed material in the asset (in the internal documentation, referred to above).

Consistency of Coverage

It is important to make sure there is consistency of coverage on key topics regarding the asset. The lack of complete documentation for an asset can significantly increase the cost of reuse and is contrary to the business value proposition effective asset-based development can provide.

For example, if an asset does not provide sufficient coverage of the required context and anticipated usage, the asset consumer may spend considerable time with the downloaded asset only to find out, hours or days later, what the actual, necessary context and usage of the asset is, and that the asset did not match the consumer's needs. This scenario significantly increases the reuse costs and decreases the potential savings.

If documentation is downloaded with the asset, ensure that it follows a similar look and feel, where possible, to the to online documentation. By decreasing the friction in the reuse transactions you can lower the costs of reuse.

Reusable Asset Specification

Organizing the external and internal documentation using the Reusable Asset Specification (RAS) structure provides consistency of coverage on key topics regarding the asset. For more information on the RAS, including details on what information can be captured for an asset, see Concept: Reusable Asset Specification.