Any reason why a tool as superb as sensu has sucky documentation on
All the Installation and Setup links to the disk-checks install and setup. I wonder why is that… ?
gem install sensu-plugins-disk-checks
I wonder why there is no detailed documentation on the plugins. Why only the commands are mentioned ?
check-ping for example has no documentation
On Friday, October 7, 2016 at 1:58:21 PM UTC+5:30, Siddharth Jagtiani wrote:
Any reason why a tool as superb as sensu has sucky documentation on
All the Installation and Setup links to the disk-checks install and setup. I wonder why is that… ?
gem install sensu-plugins-disk-checks
I wonder why there is no detailed documentation on the plugins. Why only the commands are mentioned ?
While I don’t like Siddharth’s wording, I have to admit that I also found the plugin docs more than lacking.
By now I’ve arrived at the point where I always check the ruby files and see which parameters are available
instead of hoping any of the authors of any plugin felt it necessary to write anything useful into the readme at
all.
Did we lose all the docs with the switch from one central repository to individual repositories or were lots of
plugins previously accepted without any form of documentation? Certainly it would not be that hard to write
some lines of general usage, the most common if not all supported parameters as well as prerequisites
directly into the readme instead of having users read the source!
I’m happy to contribute here and there to help fill the gaps.
IMHO the metrics need documentation the most since I have recently started collecting diverse metrics
by using metrics scripts from multiple plugins but there simply are values for which I don’t even understand
what they are supposed to measure. I don’t think that having potential users hunt for a simplistic description
what they are measuring is a good experience.
On Friday, October 7, 2016 at 10:28:21 AM UTC+2, Siddharth Jagtiani wrote:
Any reason why a tool as superb as sensu has sucky documentation on
All the Installation and Setup links to the disk-checks install and setup. I wonder why is that… ?
gem install sensu-plugins-disk-checks
I wonder why there is no detailed documentation on the plugins. Why only the commands are mentioned ?
Siddharth,
We are a small but growing team behind Sensu. As a software platform that started out life as a purely open source / community-driven project for several years before any commercial backing/offering became available, there are several areas (including plugin documentation) that we are working hard to improve. Although this won’t change overnight, it is one of our top priorities to help establish and incentivize documentation standards for the plugin community. In the interim, support for Sensu is available for as little as $50/mo and we’re happy to help with plugin-related issues. 
Thank you for choosing Sensu!
–
#monitoringlove
Caleb // Team Sensu
On Friday, October 7, 2016 at 1:28:21 AM UTC-7, Siddharth Jagtiani wrote:
Any reason why a tool as superb as sensu has sucky documentation on
All the Installation and Setup links to the disk-checks install and setup. I wonder why is that… ?
gem install sensu-plugins-disk-checks
I wonder why there is no detailed documentation on the plugins. Why only the commands are mentioned ?
Hello Alexander, Siddharth, and others!
While I don’t like Siddharth’s wording, I have to admit that I also found the plugin docs more than lacking.
By now I’ve arrived at the point where I always check the ruby files and see which parameters are available
instead of hoping any of the authors of any plugin felt it necessary to write anything useful into the readme at
all.
I agree that this is the current reality and a real problem that needs to be addressed.
Did we lose all the docs with the switch from one central repository to individual repositories or were lots of
plugins previously accepted without any form of documentation?
You’re spot on here.
Almost every project under the Sensu Plugins GitHub organization originated from
the now-deprecated monolithic repository of plugins at GitHub - sensu/sensu-community-plugins: Sensu community plugins for checks, handlers, & mutators..
Documentation available there was generally limited to code comments, at best. Such comments
are not always updated to reflect subsequent code changes.
I’m happy to contribute here and there to help fill the gaps.
IMHO the metrics need documentation the most since I have recently started collecting diverse metrics
by using metrics scripts from multiple plugins but there simply are values for which I don’t even understand
what they are supposed to measure. I don’t think that having potential users hunt for a simplistic description
what they are measuring is a good experience.
Pull requests are always welcome and documentation PRs doubly so! We also need to do a better job of making it
possible for the sensu-plugins.io website to accept outside contributions, e.g. improving the installation
documentation Siddharth has mentioned.
I have only recently become involved with the Sensu Plugins project, and I know there’s room for
improvement.
At the risk of leaving someone out I want to publicly thank the team of Sensu Plugins community
volunteers, namely Mathias Bogaert, Eric Heydrick, Matty Jones, Tim Smith, and, Shane Starcher,
who continue to advance the state of the Sensu ecosystem through this project. Those of us on
Team Sensu working full-time to develop and support both Sensu Core and Sensu Enterprise
are very thankful for your contributions.
What’s working in our favor here is the automated pipeline established by the Sensu Plugins team,
making it easier to release updated plugin gems. Even with automation in place the combined scope
of the various plugin projects is vast, but we remain committed to incremental improvement and
welcome your suggestions.
On Friday, October 7, 2016 at 5:54:38 AM UTC-6, Alexander Skiba wrote:
–
Cameron // Team Sensu
Hello All,
I dont like my wording too. Sorry for that.
Just that I have been trying to get sensu working in very small steps. As compared to shinzen, sensu is a lot better. The fact that I can move ahead in small steps is great.
Caleb,
I would if I could, but I think I can contribute on editing the documentation. Please do guide me, I would like to help in editing the documentation.
The documentation needs very little to get it right. Just things like parameters, and what they do and what are their limits.
Also a way to install the plugins. The current documentation is incorrect and incomplete.
Can I get access to the old documentation ? I’ll start looking at that may be.
Siddharth
On Saturday, October 8, 2016 at 1:34:48 AM UTC+5:30, Cameron Johnston wrote:
Hello Alexander, Siddharth, and others!
On Friday, October 7, 2016 at 5:54:38 AM UTC-6, Alexander Skiba wrote:
While I don’t like Siddharth’s wording, I have to admit that I also found the plugin docs more than lacking.
By now I’ve arrived at the point where I always check the ruby files and see which parameters are available
instead of hoping any of the authors of any plugin felt it necessary to write anything useful into the readme at
all.
I agree that this is the current reality and a real problem that needs to be addressed.
Did we lose all the docs with the switch from one central repository to individual repositories or were lots of
plugins previously accepted without any form of documentation?
You’re spot on here.
Almost every project under the Sensu Plugins GitHub organization originated from
the now-deprecated monolithic repository of plugins at http://github.com/sensu/sensu-community-plugins.
Documentation available there was generally limited to code comments, at best. Such comments
are not always updated to reflect subsequent code changes.
I’m happy to contribute here and there to help fill the gaps.
IMHO the metrics need documentation the most since I have recently started collecting diverse metrics
by using metrics scripts from multiple plugins but there simply are values for which I don’t even understand
what they are supposed to measure. I don’t think that having potential users hunt for a simplistic description
what they are measuring is a good experience.
Pull requests are always welcome and documentation PRs doubly so! We also need to do a better job of making it
possible for the sensu-plugins.io website to accept outside contributions, e.g. improving the installation
documentation Siddharth has mentioned.
I have only recently become involved with the Sensu Plugins project, and I know there’s room for
improvement.
At the risk of leaving someone out I want to publicly thank the team of Sensu Plugins community
volunteers, namely Mathias Bogaert, Eric Heydrick, Matty Jones, Tim Smith, and, Shane Starcher,
who continue to advance the state of the Sensu ecosystem through this project. Those of us on
Team Sensu working full-time to develop and support both Sensu Core and Sensu Enterprise
are very thankful for your contributions.
What’s working in our favor here is the automated pipeline established by the Sensu Plugins team,
making it easier to release updated plugin gems. Even with automation in place the combined scope
of the various plugin projects is vast, but we remain committed to incremental improvement and
welcome your suggestions.
–
Cameron // Team Sensu
I would if I could, but I think I can contribute on editing the documentation. Please do guide me, I would like to help in editing the documentation.
The documentation needs very little to get it right. Just things like parameters, and what they do and what are their limits.
I just wrote in #sensu on Freenode:
In response to the plugin doc discussion on the list I’m currently cloning all the plugins and will have a look at what currently exists in order to propose a somewhat standard format that can serve as a draft for all of you to give feedback on
I hope to have something to show within the next few hours that could serve as a base for discussion
Also a way to install the plugins. The current documentation is incorrect and incomplete.
Can you point out some things that are wrong, please?
Can I get access to the old documentation ? I’ll start looking at that may be.
I’m afraid there is no such thing. (correct me if I’m wrong)
On Saturday, October 8, 2016 at 12:44:50 PM UTC+2, Siddharth Jagtiani wrote:
I invite everyone to take a look at what I wrote up inspired by the docs of voxpopuli/puppet_unattended-upgrades.
My repo includes a look at the current plugin doc situation as an easily parsable table as well as suggestions for small, medium and large plugins for documentation standards.
Feedback very welcome!
On Friday, October 7, 2016 at 6:20:24 PM UTC+2, Caleb Hailey wrote:
Although this won’t change overnight, it is one of our top priorities to help establish and incentivize documentation standards for the plugin community.
The small vs large classification of plugins makes it very difficult to understand. Documentation only exists when there is confusion. I should need to form a certification on sensu, its a tool, it should be easy to use and not need documentation. With this classification, administrators need to understand the difference between small and large plugins, Why ?
Just have documentation on a -h and edit the readme.md on every plugin to have details on the documentation. Until the documentation is correctly put in place for each plugin, mark that plugin as “NOT DOCUMENTED ENOUGH” in RED BOLD. That makes sure that every developer documents the plugins correctly.
On Saturday, October 8, 2016 at 6:32:46 PM UTC+5:30, Alexander Skiba wrote:
On Friday, October 7, 2016 at 6:20:24 PM UTC+2, Caleb Hailey wrote:
Although this won’t change overnight, it is one of our top priorities to help establish and incentivize documentation standards for the plugin community.
I invite everyone to take a look at what I wrote up inspired by the docs of voxpopuli/puppet_unattended-upgrades.
My repo includes a look at the current plugin doc situation as an easily parsable table as well as suggestions for small, medium and large plugins for documentation standards.
Feedback very welcome!
The small vs large classification of plugins makes it very difficult to understand.
The classification exists because I am not sure that the small, default documentation format makes sense for plugins like aws which have many more checks and metrics than the usual ~10 or less. If left on a single page I fear that it might get unwieldy and less helpful very fast.
Documentation only exists when there is confusion. I should need to form a certification on sensu, its a tool, it should be easy to use and not need documentation.
Unfortunately, I didn’t understand what you were trying to say here 
With this classification, administrators need to understand the difference between small and large plugins, Why ?
You wouldn’t as an admin, but as plugins grow too large to have all the documentation they need fit onto one easily readable page, they’d change to the larger one, which can scale up better. That’s up to the plugin developer though and not an admin thing.
Just have documentation on a -h and
That’s something the plugins already do.
edit the readme.md on every plugin to have details on the documentation.
And that’s what we need some sort of standards for.
So, not sure what your point is given that you’re only speaking up for already existing things.
Until the documentation is correctly put in place for each plugin, mark that plugin as “NOT DOCUMENTED ENOUGH” in RED BOLD. That makes sure that every developer documents the plugins correctly.
Not my decision and not something I would support. It seems overly harsh to impose this on existing code. I would support something like this for newly created things which are under development and thus more likely to receive the proper attention to remove the warning soon(-ish).
On Tuesday, October 11, 2016 at 8:27:19 AM UTC+2, Siddharth Jagtiani wrote: