website
website copied to clipboard
openhab
Generate add-on installation instructions
For new users it's not always clear how to install add-ons.
Perhaps we can show generated installation instructions on the documentation page of each add-on?
It could for instance instruct how to install an add-on using:
- Main UI
- textual configuration
That way we won't have to add this information to the documentation of each add-on (https://github.com/openhab/openhab2-addons/pull/3162).
That was discussed multiple times and I think everybody agreed this is a wanted feature.
Personally I really don't like to write textual configuration help sections for my bindings if I myself never touch text files at all. That leads to mistakes, seen by recent fixes form the community for the mqtt documentation.
So thumbs up from me once more.
How to install an add-on is always the same procedure and thoroughly covered in https://www.openhab.org/docs/configuration/addons.html, so I tend to agree with https://github.com/openhab/openhab2-addons/pull/3162#issuecomment-359876239 and fail to see why it would have to be repeated in 300+ pages.
We could however put a link on a top of https://www.openhab.org/addons/ to https://www.openhab.org/docs/configuration/addons.html.
why it would have to be repeated in 300+ pages
If you get to an add-on documentation page via the community forum or a Google search you will never see this information.
I think some other issues on the add-ons page are:
- New users do not know that the "System Integrations" category is named "Misc" in Paper UI. The "io" label below these items also adds to the confusion.
- The UI add-ons are missing from this page.
Perhaps some improvements can also be made to Paper UI and HABmin so it's easier to search over all add-ons instead of just a single category.
@ghys Also see this issue and related forum topics: https://github.com/openhab/openhab2-addons/pull/4766
People apparently don't read the general openHAB documentation. They go straight for the binding doc and expect to find all kind of syntax information and examples. You now could say this is peoples fault, the problem is, those people are "spamming" the community forum with questions.
The only counter measure is to make the binding documentation more self-contained / contain more references to actual docs/ documentation.
named "Misc"
I was surprised when I saw the REST responses for configuration categories. There is really just "misc" and I expected the categories of the webpage. I think this is a core issue actually. There shouldn't be "misc" at all, only those categories we have on the webpage.
I might not be "typical people" but I've read most of the generic documents (thing setup, item setup, etc) multiple times. I still go right for the binding document when I'm getting ready to setup a new binding because I feel like I have a good general understanding of the overall setup and I want to see examples for the specific new binding.
Maybe we could generate some kind of table/list with some useful links for the addons. Or a sidebar to the right with those infos/links, while browing through the addons section.
It's not just about not wanting to read, the general documentation has moved on since I started using addons.cfg
Just like @crxporter I now go directly to a binding. yet I always had trouble finding out the name to use. I now understand it can be found in the URL, yet I think that could be more obvious.
I understand we don't want to do that for 300 pages manually. Yet this might be a good solution for a generated manual piece of text on the bindings page.
How about a link to a FAQ section at the top most position of the side drawer? See red arrow in attached picture. Anything that is always visible. Under that section there could be link to installation instructions and alike.
