Writing README for modules
Guide for writing a good README file for modules.
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.
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.
It should be mentioned whether your module is Input, Processing or Output. This information is helpful when connecting your module with other modules.
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.
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.
It also gives you an idea that a module was written in Python.
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.
Input to this module is JSON body single object or array of objects:
"<INPUT_LABEL>": <Input data>,
Example single object:
Example array of object:
Input to this module is:
- JSON body single object, example:
- array of JSON body objects, example:
Output of this module is JSON body, in example:
Images file, that will be sent via HTTP POST Method with Form data, and key as image.
This module does not produce any output except Slack notifications.
In your module's README file, you should include any other information that you might consider useful for other developers.
- 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:
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.