openhab-docs
openhab-docs copied to clipboard
openhab
Define minimum requirements for doc pages
I am mostly referring to addons documentation, but this may apply to all doc pages in one way or the other.
When looking through the documentation of the addons, I realized that they seem to follow a common structure, but content-wise they are often quite different. This is what I often miss and think should be required for a good documentation page:
- Is a channel read/write, read-only or write-only?
- In what unit is a value provided? For example, "duration" could be in milliseconds, seconds, minutes?
- Advanced settings are often not explained at all
It often takes a lot of research, sometimes even a close look at the code, to answer the above questions. On the other hand, it should be easy to include the info for the one who originally created the documentation, while at the same time, it easy to forget this, because at that moment, for the author, it may appear to be so obvious.
So I guess it makes sense to add these requirements to the template or to some kind of quality gateway – not sure how you usually handle this?
There is already a template for addons. It gets generated, when you use the binding skeleton and gives some advice on what to write down for documentation.
Additionally the maintainer take a look on binding documentation too, when reviewing Pull Requests. Maybe one of the @openhab/2-x-add-ons-maintainers could describe/explain this a bit and tell us what the criteria is and how this done for additions to an existing binding.
We could write something down in the Pull request template, but there's already plenty of information shown.
I think it would be a good idea to take a look at some updates for https://github.com/eclipse/smarthome/blob/master/tools/archetype/binding/src/main/resources/archetype-resources/README.md
Maybe we should provide an example table.
If someone has the time we could invite certain people to review the README before merging a PR.
I've just discovered that the template misses some basic requirements, while on the other hand, it asks for "pictures, a YouTube video, etc. to give an impression of what can be done with this binding". While it would be nice, I guess this is a heavy requirement!
I'd propose that we use an RFC-like terminology to make clear what MUST, what SHOULD, and what CAN be in the docs. What do you think?