End-user documentation requirements

This section presents the following topics:

Provide KM Context-Sensitive Online Help

The KM MUST included a context-sensitive online help system for each supported console.

The following platform-specific help files are required:

• WinHelp for the PATROL Console for Microsoft Windows
• NetHelp for the PATROL Console for UNIX
• Compiled HTML (.chm) Help for PATROL Central - Microsoft Windows Edition
• Browser-hosted HTML (.jar) Help for PATROL Central - Web Edition

For more information about KM Help, see KM help files.

Provide documentation in electronic form

The documentation must be available in electronic form using PDF or HTML format.

Provide instructions for installing and deploying

The documentation must include step-by-step instructions for installing and deploying the KM.

Provide instructions for uninstalling

The documentation must include step-by-step instructions for uninstalling the KM.

Provide configuration steps

The documentation must include step-by-step instructions on how to configure the KM.

The instructions must apply to all supported consoles.

Document required accounts and privileges on OS

The documentation must clearly identify the type of account privileges required and user accounts needed on the OS to have a fully operational KM.

Document loss of functionality due to lack of privileges

The documentation must clearly identify what functionality, if any, is lost when the KM does not have the required user accounts and privileges.

For information about documenting required user accounts and privileges, see Document required accounts and privileges on OS.

List supported operating systems

The documentation must list the operating environments supported by the KM, including the monitored application versions and PATROL versions.

Document platform issues

The documentation must document any portability issues, inconsistencies, or lack of functionality that occurs across platforms.

If a KM does not operate with complete functionality on all supported platforms, note the platforms that have limited functionality and note what functionality is not available on the platform in the documentation.

Provide reference information

The documentation must include reference information for all PATROL KM components. For more information about reference for PATROL KMs, see Documenting KM reference information.

Document inter-class dependencies

The documentation must list and describe inter-class dependencies. Inter-class dependencies include instances where menu commands, InfoBoxes, parameters, or parameter values depend on the value of parameters from other application classes. This requirement can be fulfilled by using the Value set by field in the online Help. For more information about reference for PATROL KMs, see Documenting KM reference information.

Document Agent to Agent communication

If the KM uses agent to agent communication, the documentation must include descriptions and uses of inter-agent communications.

This also applies to applications using tools like xpc, patrolcli, and the PEMAPI.

Document how to access the Help system

The documentation must include instructions on how to access the KM Help system on all supported PATROL consoles.

Document directory and file use

The documentation must describe any directory or file usage, with permissions (read, write, execute), outside of the BMC Software installation directory.

Document security level differences

The documentation must explain any differences in KM behavior at different PATROL security levels (0 through 4).

Document the KML file

The documentation must include the contents and a description of the KMs loaded by the .kml file.

List executables and services

The product documentation must provide a list of executable files, binaries, services, and processes that are included with the KM.

Document KM structure hierarchy

The product documentation must provide a hierarchical map or tree structure that shows the KM hierarchy. The following figure shows a typical KM hierarchy. 

 KM hierarchy map 

Provide KM online Help TOC

The TOC of each Help system must roll up into one book with the following naming convention: 

prod_name v V.R

Provide KM version in online Help

The KM name and version number must appear in the title bar of the TOC and Help windows in the following format: 

prod_name Help v V.R

Document if the KM enables or disables an application class

If the KM programmatically enables or disables an application class, the documentation must describe the conditions when the KM enables or disables the application class.

Document if the KM adjusts parameter settings

If the KM programmatically adjusts parameter settings, the documentation must describe the conditions when the KM adjusts parameter settings. 

Parameter settings include the following:

• Changing alarm range thresholds and recovery actions
• Activating or deactivating alarm ranges
• Activating or deactivating parameters

Document if the KM sets the parameter status

If the KM programmatically sets the parameter status, the product documentation must describe the conditions when the KM sets the parameter status.

List files created by the KM

The documentation must list all files that are created by the KM.

Provide documentation for other requirements

The product documentation must document the following issues:

• State the use of ActiveX controls
• Install and uninstall properly
• Support multiple application instances
• Limit the number of discovered instances
• Limit cumulative data
• Use KM protocol security
• Document Windows advanced rights
• Document group use

The following list describes the requirements from other sections that might require documentation:

• A KM that uses ActiveX controls must be designated for use on Windows platforms only. If the ActiveX control is only used on Windows, and the KM supports other platforms, the KM might document the differences when the KM is not used on Windows.
• The KM must install and uninstall on all supported platforms. If the KM does not remove all files, the KM must document what is left after the KM is uninstalled.
• The KM must support multiple instances or state in the product documentation that it does not support multiple instances of an application. If the KM does not support multiple instances of an application class, the KM must note this in the documentation.
• When it is realistic that the KM discovers more than 50 instances of an application it is monitoring, the KM must provide a method for limiting the number of instance icons that are displayed. When more than 50 instances might be created for a certain application and your KM does not nest them to help improve performance, the documentation must describe how to limit the number of instances being discovered and the performance impact of monitoring a large number of instances.
• If the KM generates more than 20 MB of cumulative data files per week, the KM must either include an automated clean-up mechanism (unless implemented as a circular file) or document this information in the product documentation.
• If the KM uses protocols other than the PATROL protocols, the KM must document the use of the protocols so that customers can understand their level of security risk.
• If the KM runs on Windows, the KM must document the need for advanced user rights and what functionality will be disabled (loss of functionality) if each of the advanced rights does not exist.
• The KM must document the need for the agent default account to belong to administrator type groups (Administrators, Domain Admin, etc.) and what functionality will be disabled (loss of functionality) if the agent default account is not a member of the group.