Documenting your plugin

When documenting your plugin for users for the New Relic Plugins product, include requirements and procedures to install, configure, use, troubleshoot, uninstall, and contact your support resources.

Documentation requirements

Here is a summary of the types of information to include in your plugin documentation.

Documentation requirements Guidelines
Title Descriptive title; for example, "Wikipedia plugin for New Relic Plugins."
Table of contents List of main topics with anchors to each section.
Description

Explanation of how the plugin can be used with New Relic Plugins to monitor and improve the associated software's performance. Which systems does it monitor (for example, memcache, versions X-Y, on the local host, sets and gets)? What problem does it solve?

Plugin requirements

Requirements or dependencies; for example:

  • New Relic subscription level: Any (If your plugin agent requires specific permissions levels from the components (instances) it monitors, be sure to document that.)
  • Internet access via SSL (HTTPS)
  • Supported operating systems
  • Minimum environment requirements (Java, Ruby, glibc, etc.)
  • Supported monitored systems
  • Any known limitations
Metrics source documentation

Plugin users may not be familiar with all the metrics displayed, their source, what the metrics mean, etc. If you have documentation that provides these details, be sure to include links to that information. For example:

  • Description of data expected from source, frequency, mechanism, etc.; for example, "Data is read from a file socket and exported from the source once per second.")
  • Description of data itself; for example, a well-formatted JSON such as {X: {y: z}}
  • Description of data being sent; for example, average response time in milliseconds, of a set or get, taken over a minute, recorded from the specified data
Installation

Step-by-step procedures to obtain and install the plugin.

Note: Do not require "su" or "sudo" permission in order to install your agent or support software unless absolutely required. These requirements must be limited in scope and well documented. For more information, see Plugin security.

Configuration Instructions to configure the plugin, expected format, and how to set them. Include how to find the user's New Relic license key: From the New Relic menu bar, select (account) > Account settings. (For example, include a hyperlink to New Relic's license key documentation.)
Troubleshooting

Include instructions as applicable; for example:

  • How to resolve common problems: Unable to connect to New Relic Plugins, unable to connnect to the monitored server, incorrect license key
  • How to enable logging and/or verbose logging
  • How to restart the plugin
  • How to test connectivity to New Relic Plugins
  • How to handle errors; for example, failure to read, aggregate, or send data
Disabling and uninstalling

Questions to consider:

  • Are there other dependencies before disabling or uninstalling the plugin? For example, are there any special procedures your plugin users need to know in order to have their operating system stop the process from running, so that they can remove components (instances) from their installed plugin?
  • Can you temporarily disable and then re-enable the plugin (for example, for troubleshooting or updating it), or must you completely uninstall and reinstall?
  • Can the uninstall procedure be done from a command line?
Support resources Instructions on how to contact your organization for support; for example, your support email address, link to your support page, etc.

Style guidelines

New Relic recognizes that you have your own documentation style, but we encourage you to mirror our documentation look, feel, and tone for your own plugin documentation. A consistent style for any plugin documentation, regardless of who publishes it, will help to support the best user experience.

Here are some recommended documentation guidelines to follow:

  • Use a professional tone. Save a more casual, breezy style for your marketing materials or blog posts, where your personality can shine.
  • Separate the "what" and the "why" from the "how." Write your introductory information about what the plugin is and why it's useful, before you write the specific procedures about how to install and use it.
  • Create step-by-step procedures. If the procedure has more than 9 steps, then break it into multiple procedures.
  • Be clear, direct, and concise. Tell plugin users what to do, not what they "should" do.
  • Label images with descriptive captions. If the only thing your plugin users look at on the page is your screenshot, does its caption tell them why it matters, what is most important, or what to do?
  • Include relevant cross references. Provide links to other useful documents, web links, and support contacts.

For more help

Additional documentation resources include:

  • Supporting your plugin (resources for plugin users to contact your organization, and resources for your plugin publishers to contact New Relic for support)
  • Publishing your plugin (procedures to make your plugin publicly accessible to users via Plugin Central in the New Relic Plugins product, or unlisted for private use)

Recommendations for learning more: