[WIP] Initial migration of doc contents to USAGE.md

[Confectrician]

CC: @kubawolanin and @ThomDietrich
Ref: openhab/openhab-google-assistant#40 (comment)

Closes #93

This is the WIP migration PR for vscode,
since we want to generalize the process of getting external documentation articles.
I have started here, because we don't sync anything vscode related yet.

PLEASE NOTE This is just a raw cut, copy and past for now.
Maybe this would be the right time to also make some improvements to usage and readme.

Goal

• Migrate to docs, docs/images and USAGE.md
• Update and improve USAGE.md since we are touching it anyways now (suggestions welcome)
• User README.md for repo and contribution information
• Anything that i forgot now

Signed-off-by: Jerome Luckenbach github@luckenba.ch

[Confectrician]

@kubawolanin

My suggestion would be to clean up CONTRIBUTING a bit and move some technical/repo contents to readme.
So we could split up the tech stuff and the legal guideline stuff nicely.

Also there was an attempt to share/sync the guidelines over all repos some time ago in an openhab-docs issue.
There is not much progress currently, but we would be prepared for the future, if we store the stuff that is only related to vscode in the readme file.

wdyt?

[Confectrician]

Another question that has come to my mind:

Is the visual studio marketplace description served from the readme file on a fixed basis or could we configure to use usage.md while publishing?

[kubawolanin]

Is the visual studio marketplace description served from the readme file on a fixed basis or could we configure to use usage.md while publishing?

It's served from README file on strict basis so I'm afraid we cannot split it entirely.
People are relying on the page both in Marketplace and Extensions page.
So we'll need to be clever with choosing what to present there and what can be moved to the detailed doc page.

[Confectrician]

Or we have to replace the readme.md content while publishing a new release with a script or a similiar solution.

Most of the time readme and usage will be read here or in the docs.

[Confectrician]

I have thought about it several times now.

The case publish to marketplace is not as frequent as we are updating the usage or generate the website.
Also we would have to make another exception in handling external docs for this repo.
We already have many different ways of aquiring content for the documentation, which make it complicated.

My vote would be for:

• readme es a repo information and contributors documentation
• docs folder for user guidance and information
• reference usage in readme
• code some kind of script which generates a user friendly readme for the marketplace on the fly before or while the extension is beeing published.
• maybe do some ci/build stuff for this in the future.

@ThomDietrich i would love to hear your opinion about it.

[Confectrician]

Reference #88.
We should check for 3rd Party references, while updating the content.

[Confectrician]

To much changes meanwhile.

We have to update the readme anyway and then give it a clean try.