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.
|