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.
Here is a summary of the types of information to include in your plugin documentation.
|Title||Descriptive title; for example, "Wikipedia plugin for New Relic Plugins."|
|Table of contents||List of main topics with anchors to each section.|
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?
Requirements or dependencies; for example:
|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:
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.)|
Include instructions as applicable; for example:
|Disabling and uninstalling||
Questions to consider:
|Support resources||Instructions on how to contact your organization for support; for example, your support email address, link to your support page, etc.|
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)