Add Alexa to the docs

[mboremski]

Alexa has a "skill" for openHAB (jeah).
https://community.openhab.org/t/official-alexa-smart-home-skill-for-openhab-2/23533
Should we take that to the docs too?

[ThomDietrich]

Yes we should! We totally missed to do so.
A README already exists, just needs to be copied: https://github.com/openhab/openhab-alexa/blob/master/README.md

This is related to #62 where I wanted to update the copying of external content.

In the meantime we could already improve the content of this README. @mboremski do you see any need for improvements? Best!

[ThomDietrich]

Addition: After a first look it became clear to me, that the article can not be copied 1:1. It contains too many technical details not needed for the general openHAB docs article. I'd say an enhanced version of the second part of the README would be what we need. Would you be interested to build this document? I'd still leave it in the openhab-alexa repo, maybe as a new file USAGE.md.

[mboremski]

sorry for the late reply.
I am not sure if the alexa-repo ist the right place to manage the README/USAGE.
After the openhab-skill has been certified by Amazon (I think) there is just a readme needed that explains how to handle the Items. Maybe a howto integrate the skill in alexa-app, but thats easy stuff.

I could try to use some useful snipets out of the actual README an write a new one.
But I am really new in taking part on gut-hub.
Cold you give me a hint whats the best way to place my proposal?
TY

[mboremski]

Ehm. I tried around a bit with a USAGE.md file, fount out that to contribute i should make a fork.
Thats what i did right now and I uploaded the file here

could you have a look?

[Confectrician]

Hi @mboremski,

About the workflow:

Next step would be to create an pull request to the openhab-alexa repository.
There we can discuss and improve the text and other people can comment single text parts.
Finally the Pull Request would be "merged", which means your changes would be implemented then.

Note:
You have currently made this changes in the master branch.

Usually changes are made in new branches to prevent conflicts, when several people are working in a project.

This keeps your contribution isolated from others and can reduce conflicts.
(Luckily this is not a big deal in your case, since you introduced a new file and no one can work parallel on it meanwhile, since it is not yet existing in the official repository.)
I just wanted to mention it as an information for you. :)

First feedback about style things:

I had a first look on that usage file now.
There are some general things to change in order to deal with our build tool jekyll and some codestyle things.

We break down texts to one sentence per line.
This is mainly for keeping git clean. (Git works on a "line base")
Markdown and our build tool dont care about the additional lines and generate a nice and readable text anyways.

Also there have to be some empty lines between headlines and text parts.
This is necessary for the build engine to generate html pages from the markdown document.

Here's an example:

Your code:

Improved Version:

So my suggestion for you would be to create a pull request to the openhab alexa repo now and we continue discussion there.
If there are any GitHub questions or you need help at some point feel free to ask here and we will provide help and all informations you need. :)

[ThomDietrich]

Excellent answer @Confectrician !

One question I want to answer:

I am not sure if the alexa-repo ist the right place to manage the README/USAGE.

The openHAB project is heavily distributed among dozens of project repos. That is a good thing. Each project is part of openHAB but self-contained for one specific topic, e.g. to host all code related to the openhab-alexa skill. if changes to the skill and its features are planned, the repo should be the one and only place these changes need to be applied. Therefore the README/USAGE document should reside there as well ;)

Looking forward to your PR. Please link it here so we can follow along. Thanks for your contribution!!

[mboremski]

Hey @Confectrician
Thanks a lot for helping me with the first steps. That's really helpful.

hey @ThomDietrich
thanks too, that made it more clear to me. :)

Right now I am joinig gamescom in cologne.
I will have a deeper look in the evening..

[mboremski]

Made some changes basing on your sugestions @Confectrician and finally made my first pull request.
Tell me if I have to or can do something more.
looking forward :)

[Confectrician]

Will do that tommorow. :)

[ThomDietrich]

Hey @mboremski,
now that the file is available it's my turn to finally look into #62 and finish this long outstanding important piece. I'll be on vacation over the weekend but hopefully have time for that next week!