Plugin Documentation

Overview

One of the prerequisites when submitting a plugin for approval is documentation. Plugin documentation is necessary in order to educate users on the following:

• Objective or goal of the plugin.
• What kinds of capabilities it enables when used in a data pipeline.
• How it is configured and used (user guide).
• What changes are made to the plugin when submitting iterations.

Plugin documentation are split into two. In this section, the two kinds of documentation that need to be included in a plugin will be described in detail.

Documentation

Documentation should detail information related to the use of the plugin. It is basically a user guide which contains the following details:

1. A brief description of the plugin. If it integrates with another service, the description can include the capabilities enabled by the integration.
2. It should detail all the steps to successfully configure the plugin. It needs to describe all the configuration parameters in detail. If the plugin integrate with another service, it should also details how to setup the integration on the other end.
3. If it deals with a specific set of input data, it should also be specified (i.e. "This plugin consumes latitude and longitude coordinate pairs with timestamps. This data should be included in the input data.").

Documentation can change in between releases so it is encouraged that whenever you push a new release or update to your plugins, you also update the documentation accordingly.

Support for markdown when writing documentation is included and use of it is highly encouraged. If you are not familiar with Markdown, please see this reference on how to write using Markdown syntax.

When bootstrapping a plugin project using the Project Generator/Scaffolding (Yeoman), the documentation is README.md by default as its the one linked on the Plugin Manifest (reekoh.yml file).

Release Notes

The other documentation that needs to be included for plugins are release notes. Release notes are separate from the main documentation as its concerns are separate. It needs to list down all the updates or changes made to the plugin for the new release. The changes can be as simple as bug fixes, security patches, or even to complete rework of the plugin itself.

Support for markdown when writing release notes is included and use of it is highly encouraged. If you are not familiar with Markdown, please see this reference on how to write using Markdown syntax.

When bootstrapping a plugin project using the Project Generator/Scaffolding (Yeoman), the Release Notes are under the release-notes folder and RELEASE-v1.0.0.md is the default one linked on the Plugin Manifest (reekoh.yml). You can create one release notes file per release to detail all the changes you made and link the relevant file to the release you are submitting.