This chapter includes general advice and considerations on preparing customer documentation, as well as advice and considerations related to two specific scenarios:
Regardless of the type of partner you are (see Types of ISVs), whenever you prepare any software product to be distributed to customers, you should provide, at a minimum, documentation that includes the following:
Document completely the contents of your distribution, for example, the parts of WebLogic Server that are included: WebLogic Server, Web server plug-ins, BEA JRockit, maintenance patches, and so on. Store the version numbers of WebLogic Server and any relevant components in several easy-to-find locations. (When a customer needs to contact a support organization, having multiple records of the relevant version numbers for the software can be helpful.)
Describe completely the terms of the support and license provided with your product, and the warranty. Identify who your customers should contact, or what Web site they should use, if they need to use support services. Distinguish between the support you provide, versus that provided by BEA. (The level of support provided by BEA may depend on your support contract with BEA. See About BEA Partner Support, for more information.)
If your customers need to periodically apply BEA-provided maintenance patches to the embedded WebLogic Server software, explain to customers how to obtain and apply those patches.
Document the installation application for your product, even if WebLogic Server is installed and configured in silent mode. Describe every step the customer needs to take, such as how to download the distribution from the internet, how to identify the appropriate CD from a physical container, and how the customer chooses an item from the Start menu (if a Windows product).
Include, and identify plainly, any documentation that customers need to read before they install or use your product. Typically this information includes hardware and software prerequisites, memory and disk space requirements, and other resources that the customer will need to install or use. If applicable, this document should include any usage restrictions, or possibly any known problems that customers should know about.
This may be self-evident, but be sure to include comprehensive instructions and reference information for product use. For example, state clearly how to start and run your custom software.
If you are using the silent-mode installation, maintenance, and configuration features of WebLogic Server to install and configure your product, be sure to prepare documentation for the customer that describes the following:
user_projects
directory, patch files in the BEA_HOME
/patch_weblogic92
and BEA_HOME
/utils/bsu
directories).
If your product is designed to be installed interactively—that is, if your customers must run the installation program, followed by the Configuration Wizard—be sure to prepare documentation for the customer that describes the following:
Depending on your license agreement with BEA, you might have the ability to redistribute BEA Products Installation Guide. Explain clearly any required installation choices customers must make during the installation.
If you must include a cross-reference to related text in another part of the configuration documentation for BEA Products, be sure to make the cross-reference accurate and explicit. That is, make the cross-reference to a specific section in a document, and not simply to the entire document. Customers do not want to wade through 200 pages of documentation for details about a specific configuration choice. It is assumed that you have also created a domain template or template extension for your application. (For information about templates and template extensions, see Configuring and Installing WebLogic Applications.)
user_projects
directory) and patch files.