ISV Partners' Guide

Preparing Customer Documentation

This chapter includes general advice and considerations on preparing customer documentation, as well as advice and considerations related to two specific scenarios:

• Silent installation and configuration
• Interactive installation and configuration

 

---

General Advice on Preparing Customer Documentation

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:

• Contents of the distribution

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

• Support and license information

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

• Installation

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

• Read-first documents

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.

• User documentation

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.

 

---

Documentation for Silent-Mode Installation and Configuration

If you are using the silent-mode installation and configuration features of WebLogic Server to install and configure your product, be sure to prepare documentation for the customer that describes the following:

• The choices that were made during the installation. For example, WebLogic Server components installed and configuration details for various system resources.
• The results of the installation, such as a list of the directories and files added to the customer's system, including the files associated with the customer's domain (for example, the files in the user_projects directory).
• Location of the licenses installed, as well as the terms of the licenses. Include instructions on how customers can extend the terms of the license.

 

---

Documentation for Interactive Installation and Configuration

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:

• A comprehensive description of the steps required to install WebLogic Server.

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.

• How to start and run the Configuration Wizard to use the template, or extension template, that you have created. This documentation should state the following:
• Whether and how to create or extend an existing WebLogic domain
• How to locate the template or template extension
• The meaning of the choices that you are instructing customers to make. If multiple options are available for a given entry, explain the advantages and disadvantages of each choice.

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

• The results of the installation, such as a list of the directories and files added to the customer's system, including the files associated with the customer's domain (that is, the files in the user_projects directory).
• Locations and terms of the licenses installed, as well as instructions for extending the terms of a license.