Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Generate add-on installation instructions #152

Open
wborn opened this issue Jan 30, 2019 · 8 comments
Open

Generate add-on installation instructions #152

wborn opened this issue Jan 30, 2019 · 8 comments

Comments

@wborn
Copy link
Member

wborn commented Jan 30, 2019

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).

@davidgraeff
Copy link
Member

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.

@ghys
Copy link
Member

ghys commented Jan 31, 2019

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.

@wborn
Copy link
Member Author

wborn commented Jan 31, 2019

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.

@davidgraeff
Copy link
Member

davidgraeff commented Jan 31, 2019

@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.

@crxporter
Copy link

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.

@Confectrician
Copy link
Contributor

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.

@yveshanoulle
Copy link

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.

@gitMiguel
Copy link

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.

Huomautus 2019-12-18 000255

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

7 participants