Documenting Plugins

Plugins can provide tremendously useful functionality for users of Traffic Server, but it does them little good if there are no instructions on how to use the plugins properly. In the interest of encouraging useful documentation on all the features available to those deploying Traffic Server in their infrastructure, this section lays out a series of guidelines and offers a basic template for adding new entries to the Plugins chapter of the Administrator’s Guide.

Structure

Ideally, every plugin will provide documentation covering the following general topics (preferably in top-level sections named to match):

Introduction

A brief section in which the plugin’s core functionality is explained in a quickly digestible paragraph or two. For the sake of brevity, this section should omit discussion of configuration details in favor of providing a more 10,000 foot view of the plugin features.

Purpose

Why would someone want to use this particular plugin? What problems does it solve, or what features not attainable otherwise (through core functionality or other plugins) does it provide to an administrator or user? While not exactly a product pitch, this is the section in which the case for using the plugin at all should be made.

Dependencies

If the plugin has external dependencies, they should be listed in full, with the exception of items already required by a bare-bones Traffic Server build. If the plugin has no unusual or non-standard dependencies, this section may be safely omitted.

For example, there is no need to list a C++ compiler as a requirement, but if the plugin requires OpenCL and a specific brand of GPU expansion card to perform some wacky image transformations on cached objects - that really should be disclosed.

If any of the dependencies are optional, that should be noted as well as the functionality that may be missing should the dependency not be present.

Installation

Detailed instructions on how to install the plugin if it is not built by default with Traffic Server or requires any additional libraries, services, or applications outside of Traffic Server to be present.

If the plugin is marked stable and included by default in Traffic Server builds, then it may not be necessary to include any installation steps beyond noting that it is part of the default Traffic Server.

Configuration

Detailed instructions on how and where to provide configuration data for the plugin’s features. It is important to use reStructuredText references for all mentions of Traffic Server configuration variables, as well as their containing configuration files.

If configurations are generated by scripts included with the plugin source code, those scripts should be mentioned and their usage should be shown.

Caveats (or Limitations)

Notes about any peculiarities with the plugin, incompatibilities or strange behaviors when used in conjunction with other features, or special considerations for its deployment that might affect an administrator’s use of the plugin or their infrastructure’s architecture.

If the plugin contains known limitations (perhaps it only works with some protocols, can understand only some media types, or is especially non-performant under specific configurations) they should be noted. If possible, workarounds for these limitations should be suggested, or if none are available that should be noted.

Examples

Every plugin should aim to have at least one, complete example of its usage beginning with its basic installation, showing a complete (and ideally working) configuration, as well as sample output from Traffic Server in which the plugin’s effects may be observed.

Further Reading

Consolidated list of references to outside materials and documents which may be relevant to the plugin, such as RFCs and white papers. If the plugin is related to external projects, or has been the subject of benchmarks or articles, those may be useful to list as well.

Additional Sections

Not all plugins will fit perfectly within that list of sections. Some may require additional details, or such extended discussion that it is best to break the plugin’s documentation down a bit further. In general, it is recommended to place these additional documentation sections in between Configuration and Caveats or Limitations.

This ordering permits a quick scanning of the plugin’s purpose, basic method of installation, and initial overview of its configuration before becoming mired down in dissertation length details of every possible configuration, warning, and trade-off that may affect deployments.

In cases where the array of configuration possibilities is extensive, it is recommended that the initial Configuration section describe the most common configuration scenario(s), while noting that there are many other possibilities that will be covered in the sections that follow. This, it is hoped, will get the usual case out of the way quickly for most Traffic Server administrators while limiting the paralysis of choice they may face otherwise.

Documentation Template

For the convenience of plugin developers, this manual includes a plugin documentation template which you may use as a base. The template includes placeholders, with markup, for common features of the documentation which may be relevant for your plugin. Developers are very strongly encouraged to use this template whenever possible, as a means of producing and maintaining a consistent format for plugin documentation.

Note

to be done