Writing README for modules

Search…
Guide for writing a good README file for modules.
Introducion
Here at weeve we do not have specified requirements for a module's README file yet, but there is a couple of things worth mentioning in your documentation. In this tutorial we are going to describe them.
Markdown Tutorial
If you are not familiar with Markdown and writing README files, then we recommend this free online tutorial: Markdown Tutorial​
README Recommended Fields:
Since your modules might be used by other developers from your company or externals (if you decide to make your modules public), then it is important to communicate to them some information that will be useful in the context of weeve ecosystem. Although we do not have strict company policy on README files, we recognize the following information to be helpful.
Docker Image
Currently weeve supports Docker, so all modules should be published to DockerHub. Hence, it is important to share a link to your image repository in DockerHub in the module's README file.
Module Type
It should be mentioned whether your module is Input, Processing or Output. This information is helpful when connecting your module with other modules.
List of Environment Variables
Another crucial element is a list of environment variables. Of course, you do not need to share values that you assigned to the environment variables of your module, but it would be useful to share variable names. These might be further used by developers when testing your module with their modules, as they could set some values to work on.
We recommend creating an environment variables table as the example bellow (this is from README of weeve Comparison Filter module):
Name
Environment Variables
Type
Description
Input Label
INPUT_LABEL
string
The input label on which anomaly is detected.
Condition
CONDITION
string
Condition for filtering data
Compare Value
COMPARE_VALUE
string
The value to compare with
List of Dependencies
List of dependencies is a list of libraries and packages that your container downloads in order to run your code. Although it cannot be modified by anyone pulling your module image from a repository, it is still useful to share this information.
For instance, this is a list of dependencies from README of weeve Comparison Filter module:
bottle==0.12.21
requests==2.27.1
It also gives you an idea that a module was written in Python.
Module Input
This is one of the most important information that must be shared in your module's README file. It is information about a type and a format of input that your module expects (it is not necessary for input modules). Therefore, a developer will understand what data can be passed to your module without breaking it. A good idea would be giving a minimum requirements for your module input data and an example to "visualize" it.
Example 1: Input to weeve HTTP Egress module as taken from module's README file:
Input to this module is JSON body single object or array of objects:
​
{
    "<INPUT_LABEL>": <Input data>,
}
​
Example single object:
​
    {
        temperature: 15,
    }
​
Example array of object:
​
    [
        {
            temperature: 15,
        },
        {
            temperature: 21,
        },
        {
            temperature: 25,
        },
    ]
Example 2: Input to weeve Cleaner module as taken from module's README file:
Input to this module is:
​
- JSON body single object, example:
    {
        "temperature": 15,
    }
​
- array of JSON body objects, example:
    [
        {
            "temperature": 15,
        },
        {
            "temperature": 17,
        }
    ]
Module Output
It is also the most important information along the Module Input. This should specify what is the format of data outputted by your module (it is not necessary for output modules).
Example 1: Output of weeve Comparison Filter module as taken from module's README file:
Output of this module is JSON body, in example:
​
    {
        "temperature": 12
    }
Example 2: Output of weeve Camera Capture module as taken from module's README file:
Images file, that will be sent via HTTP POST Method with Form data, and key as image.
Example 3: Output of weeve Slack Alert module as taken from module's README file:
This module does not produce any output except Slack notifications.
Other Information
In your module's README file, you should include any other information that you might consider useful for other developers.
If your module allows to apply some mathematic functions to a data like weeve Aggregator module does, you could include a short description of these functions:
Supported functions:
- mean (mean value that arrived within the specified interval)
- max (maximum value)
- spread (maximum - minimum value)
- median (median value recorded within the interval)
- sum (sum of all received values)
- stddv (standard deviation of values)
- count (number of data that arrived within the interval)
- first (first recorded data)
- min (minimum value)
- last (last recorded data)
If your module creates a notification alert that is later sent to a communication channels like Slack, WhatsApp or Discord, you could consider mentioning what type of alerts a user can expect. For instance, the following is mentioned in weeve Slack Alert module README:
Type
Text
warning
WARNING for MachineName! Temperature reading shows 41.19 Celsius (< 49.0 Celsius).
alarming
ALARM from MachineName! Detected an alarming reading of Temperature: 100 Celsius (> 20 Celsius).
caution
CAUTION for MachineName! Temperature is 100 Celsius (>= 20 Celsius).
broken
BROKEN device MachineName! Detected Temperature reading is -1.1 Celsius (<= -1 Celsius).
Conclusion
README files should contain all necessary information that could be useful for other developers using your modules. If you need more inspiration for README formats, you can check out weeve GitHub repo.
Project and Docker naming and versions
Icon creation for Module
Last modified 7d ago
Copy link
Outline
Introducion
Markdown Tutorial
README Recommended Fields:
Conclusion